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