001package org.fhir.ucum;
002
003/*******************************************************************************
004 * Crown Copyright (c) 2006+, Copyright (c) 2006 - 2014 Kestral Computing & Health Intersections.
005 * All rights reserved. This program and the accompanying materials
006 * are made available under the terms of the Eclipse Public License v1.0
007 * which accompanies this distribution, and is available at
008 * http://www.eclipse.org/legal/epl-v10.html
009 * 
010 * Contributors:
011 *    Kestral Computing P/L - initial implementation
012 *    Health Intersections - ongoing maintenance
013 *******************************************************************************/
014
015import java.util.Date;
016import java.util.List;
017import java.util.Set;
018
019
020/**
021 * General Ucum Service
022 * 
023 * UCUM functionality that is useful for applications that make use of UCUM codes
024 * 
025 * @author Grahame Grieve
026 *
027 */
028public interface UcumService {
029
030        /**
031         * provided for various utility/QA uses. Should not be used 
032         * for general use
033         * 
034         * @return the model
035         */
036        public abstract UcumModel getModel();
037
038        public class UcumVersionDetails {
039                private Date releaseDate;
040                private String version;
041                /**
042                 * @param releaseDate
043                 * @param version
044                 */
045                public UcumVersionDetails(Date releaseDate, String version) {
046                        super();
047                        this.releaseDate = releaseDate;
048                        this.version = version;
049                }
050                /**
051                 * @return the releaseDate
052                 */
053                public Date getReleaseDate() {
054                        return releaseDate;
055                }
056                /**
057                 * @return the version
058                 */
059                public String getVersion() {
060                        return version;
061                }
062                
063        }
064        
065        /**
066         * return Ucum Identification details for the version in use
067         */
068        public abstract UcumVersionDetails ucumIdentification();
069
070
071        /**
072         * Check UCUM. Note that this stands as a test of the service
073         * more than UCUM itself (for version 1.7, there are no known
074         * semantic errors in UCUM). But you should always run this test at least
075         * once with the version of UCUM you are using to ensure that 
076         * the service implementation correctly understands the UCUM data
077         * to which it is bound
078         *   
079         * @return a list of internal errors in the UCUM spec.
080         * 
081         */
082        public abstract List<String> validateUCUM();
083
084        /**
085         * Search through the UCUM concepts for any concept containing matching text.
086         * Search will be limited to the kind of concept defined by kind, or all if kind
087         * is null
088         * 
089         * @param kind - can be null. scope of search
090         * @param text - required
091         * @param isRegex
092         * @return
093         */
094        public abstract List<Concept> search(ConceptKind kind, String text, boolean isRegex);
095
096        /**
097         * return a list of the defined types of units in this UCUM version
098         * 
099         * @return
100         */
101        public abstract Set<String> getProperties();
102
103        /**
104         * validate whether a unit code are valid UCUM units
105         *  
106         * @param units - the unit code to check
107         * @return nil if valid, or an error message describing the problem
108         */
109        public abstract String validate(String unit);
110
111        /**
112         * given a unit, return a formal description of what the units stand for using
113         * full names 
114         * @param units the unit code
115         * @return formal description
116         * @throws UcumException 
117         * @throws OHFException 
118         */
119        public String analyse(String unit) throws UcumException ;
120        
121        /**
122         * validate whether a units are valid UCUM units and additionally require that the 
123         * units from a particular property
124         *  
125         * @param units - the unit code to check
126         * @return nil if valid, or an error message describing the problem
127         */
128        public abstract String validateInProperty(String unit, String property);
129
130        /**
131         * validate whether a units are valid UCUM units and additionally require that the 
132         * units match a particular base canonical unit
133         *  
134         * @param units - the unit code to check
135         * @return nil if valid, or an error message describing the problem
136         */
137        public abstract String validateCanonicalUnits(String unit, String canonical);
138
139        /**
140         * given a set of units, return their canonical form
141         * @param unit
142         * @return the canonical form
143         * @throws UcumException 
144         * @throws OHFException 
145         */
146        public abstract String getCanonicalUnits(String unit) throws UcumException ;
147
148  /**
149   * given two pairs of units, return true if they sahre the same canonical base
150   * 
151   * @param units1
152   * @param units2
153   * @return
154   * @throws UcumException 
155   * @ 
156   */
157  public abstract boolean isComparable(String units1, String units2) throws UcumException ;
158  
159        /**
160         * for a given canonical unit, return all the defined units that have the 
161         * same canonical unit. 
162         * 
163         * @param code
164         * @return
165         * @throws UcumException 
166         * @throws OHFException
167         */
168        public abstract List<DefinedUnit> getDefinedForms(String code) throws UcumException ;
169
170        /**
171         * given a value/unit pair, return the canonical form as a value/unit pair
172         * 
173         * 1 mm -> 1e-3 m
174         * @param value
175         * @return
176         * @throws UcumException 
177         * @throws OHFException 
178         */
179        public abstract Pair getCanonicalForm(Pair value) throws UcumException ;
180
181        /**
182         * given a value and source unit, return the value in the given dest unit
183         * an exception is thrown if the conversion is not possible
184         * 
185         * @param value
186         * @param sourceUnit
187         * @param destUnit
188         * @return the value if a conversion is possible
189         * @throws UcumException 
190         * @throws OHFException
191         */
192        public abstract Decimal convert(Decimal value, String sourceUnit, String destUnit) throws UcumException ;
193
194        /**
195         * multiply two value/units pairs together and return the result in canonical units
196         * 
197         * Note: since the units returned are canonical, 
198         * @param o1
199         * @param o2
200         * @return
201         * @throws UcumException 
202         * @ 
203         */
204        public abstract Pair multiply(Pair o1, Pair o2) throws UcumException ;
205
206
207        /**
208         * given a set of UCUM units, return a likely preferred human dense form
209         * 
210         * SI units - as is. 
211         * Other units - improved by manual fixes, or the removal of [] 
212         * 
213         * @param code
214         * @return the preferred human display form
215         */
216        public abstract String getCommonDisplay(String code);
217
218
219
220}