Source code

001package org.hl7.fhir.dstu2016may.utils;
002
003/*
004  Copyright (c) 2011+, HL7, Inc.
005  All rights reserved.
006  
007  Redistribution and use in source and binary forms, with or without modification, 
008  are permitted provided that the following conditions are met:
009    
010   * Redistributions of source code must retain the above copyright notice, this 
011     list of conditions and the following disclaimer.
012   * Redistributions in binary form must reproduce the above copyright notice, 
013     this list of conditions and the following disclaimer in the documentation 
014     and/or other materials provided with the distribution.
015   * Neither the name of HL7 nor the names of its contributors may be used to 
016     endorse or promote products derived from this software without specific 
017     prior written permission.
018  
019  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
020  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
021  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
022  IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
023  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
024  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
025  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
026  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
027  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
028  POSSIBILITY OF SUCH DAMAGE.
029  
030 */
031
032
033
034import java.util.List;
035import java.util.Locale;
036import java.util.Set;
037
038import org.hl7.fhir.dstu2016may.formats.IParser;
039import org.hl7.fhir.dstu2016may.formats.ParserType;
040import org.hl7.fhir.dstu2016may.model.CodeSystem;
041import org.hl7.fhir.dstu2016may.model.CodeSystem.ConceptDefinitionComponent;
042import org.hl7.fhir.dstu2016may.model.CodeableConcept;
043import org.hl7.fhir.dstu2016may.model.Coding;
044import org.hl7.fhir.dstu2016may.model.ConceptMap;
045import org.hl7.fhir.dstu2016may.model.OperationOutcome.IssueSeverity;
046import org.hl7.fhir.dstu2016may.model.Resource;
047import org.hl7.fhir.dstu2016may.model.StructureDefinition;
048import org.hl7.fhir.dstu2016may.model.ValueSet;
049import org.hl7.fhir.dstu2016may.model.ValueSet.ConceptSetComponent;
050import org.hl7.fhir.dstu2016may.model.ValueSet.ValueSetExpansionComponent;
051import org.hl7.fhir.dstu2016may.terminologies.ValueSetExpander.ValueSetExpansionOutcome;
052
053
054/**
055 * This is the standard interface used for access to underlying FHIR
056 * services through the tools and utilities provided by the reference
057 * implementation. 
058 * 
059 * The functionality it provides is 
060 *  - get access to parsers, validators, narrative builders etc
061 *    (you can't create these directly because they need access 
062 *    to the right context for their information)
063 *    
064 *  - find resources that the tools need to carry out their tasks
065 *  
066 *  - provide access to terminology services they need. 
067 *    (typically, these terminology service requests are just
068 *    passed through to the local implementation's terminology
069 *    service)    
070 *  
071 * @author Grahame
072 */
073public interface IWorkerContext {
074
075  // -- Parsers (read and write instances) ----------------------------------------
076
077  /**
078   * Get a parser to read/write instances. Use the defined type (will be extended 
079   * as further types are added, though the only currently anticipate type is RDF)
080   * 
081   * XML/JSON - the standard renderers
082   * XHTML - render the narrative only (generate it if necessary)
083   * 
084   * @param type
085   * @return
086   */
087  public IParser getParser(ParserType type);
088
089  /**
090   * Get a parser to read/write instances. Determine the type 
091   * from the stated type. Supported value for type:
092   * - the recommended MIME types
093   * - variants of application/xml and application/json
094   * - _format values xml, json
095   * 
096   * @param type
097   * @return
098   */   
099  public IParser getParser(String type);
100
101  /**
102   * Get a JSON parser
103   * 
104   * @return
105   */
106  public IParser newJsonParser();
107
108  /**
109   * Get an XML parser
110   * 
111   * @return
112   */
113  public IParser newXmlParser();
114
115  /**
116   * Get a generator that can generate narrative for the instance
117   * 
118   * @return a prepared generator
119   */
120  public INarrativeGenerator getNarrativeGenerator(String prefix, String basePath);
121
122
123  // -- resource fetchers ---------------------------------------------------
124
125  /**
126   * Find an identified resource. The most common use of this is to access the the 
127   * standard conformance resources that are part of the standard - structure 
128   * definitions, value sets, concept maps, etc.
129   * 
130   * Also, the narrative generator uses this, and may access any kind of resource
131   * 
132   * The URI is called speculatively for things that might exist, so not finding 
133   * a matching resouce, return null, not an error
134   * 
135   * The URI can have one of 3 formats:
136   *  - a full URL e.g. http://acme.org/fhir/ValueSet/[id]
137   *  - a relative URL e.g. ValueSet/[id]
138   *  - a logical id e.g. [id]
139   *  
140   * It's an error if the second form doesn't agree with class_. It's an 
141   * error if class_ is null for the last form
142   * 
143   * @param resource
144   * @param Reference
145   * @return
146   * @throws Exception
147   */
148  public <T extends Resource> T fetchResource(Class<T> class_, String uri);
149
150  /**
151   * find whether a resource is available. 
152   * 
153   * Implementations of the interface can assume that if hasResource ruturns 
154   * true, the resource will usually be fetched subsequently
155   * 
156   * @param class_
157   * @param uri
158   * @return
159   */
160  public <T extends Resource> boolean hasResource(Class<T> class_, String uri);
161
162  // -- profile services ---------------------------------------------------------
163  
164  public List<String> getResourceNames();
165  public List<StructureDefinition> allStructures();
166  
167  // -- Terminology services ------------------------------------------------------
168
169  // these are the terminology services used internally by the tools
170  /**
171   * Find the code system definition for the nominated system uri. 
172   * return null if there isn't one (then the tool might try 
173   * supportsSystem)
174   * 
175   * @param system
176   * @return
177   */
178  public CodeSystem fetchCodeSystem(String system);
179
180  /**
181   * True if the underlying terminology service provider will do 
182   * expansion and code validation for the terminology. Corresponds
183   * to the extension 
184   * 
185   * http://hl7.org/fhir/StructureDefinition/conformance-supported-system
186   * 
187   * in the Conformance resource
188   * 
189   * @param system
190   * @return
191   */
192  public boolean supportsSystem(String system);
193
194  /**
195   * find concept maps for a source
196   * @param url
197   * @return
198   */
199  public List<ConceptMap> findMapsForSource(String url);  
200
201  /**
202   * ValueSet Expansion - see $expand
203   *  
204   * @param source
205   * @return
206   */
207  public ValueSetExpansionOutcome expandVS(ValueSet source, boolean cacheOk);
208  
209  /**
210   * Value set expanion inside the internal expansion engine - used 
211   * for references to supported system (see "supportsSystem") for
212   * which there is no value set. 
213   * 
214   * @param inc
215   * @return
216   */
217  public ValueSetExpansionComponent expandVS(ConceptSetComponent inc);
218
219  Locale getLocale();
220
221  void setLocale(Locale locale);
222
223  String formatMessage(String theMessage, Object... theMessageArguments);
224
225  void setValidationMessageLanguage(Locale locale);
226
227  public class ValidationResult {
228    private ConceptDefinitionComponent definition;
229    private IssueSeverity severity;
230    private String message;
231    
232    public ValidationResult(IssueSeverity severity, String message) {
233      this.severity = severity;
234      this.message = message;
235    }
236    
237    public ValidationResult(ConceptDefinitionComponent definition) {
238      this.definition = definition;
239    }
240
241    public ValidationResult(IssueSeverity severity, String message, ConceptDefinitionComponent definition) {
242      this.severity = severity;
243      this.message = message;
244      this.definition = definition;
245    }
246    
247    public boolean isOk() {
248      return definition != null;
249    }
250
251    public String getDisplay() {
252      //Don't want question-marks as that stops something more useful from being displayed, such as the code
253      //return definition == null ? "??" : definition.getDisplay();
254      return definition == null ? null : definition.getDisplay();
255    }
256
257    public ConceptDefinitionComponent asConceptDefinition() {
258      return definition;
259    }
260
261    public IssueSeverity getSeverity() {
262      return severity;
263    }
264
265    public String getMessage() {
266      return message;
267    }
268  }
269
270  /**
271   * Validation of a code - consult the terminology service 
272   * to see whether it is known. If known, return a description of it
273   * 
274   *  note: always return a result, with either an error or a code description
275   *  
276   * corresponds to 2 terminology service calls: $validate-code and $lookup
277   * 
278   * @param system
279   * @param code
280   * @param display
281   * @return
282   */
283  public ValidationResult validateCode(String system, String code, String display);
284
285  /**
286   * Validation of a code - consult the terminology service 
287   * to see whether it is known. If known, return a description of it
288   * Also, check whether it's in the provided value set
289   * 
290   * note: always return a result, with either an error or a code description, or both (e.g. known code, but not in the value set)
291   *  
292   * corresponds to 2 terminology service calls: $validate-code and $lookup
293   * 
294   * @param system
295   * @param code
296   * @param display
297   * @return
298   */
299  public ValidationResult validateCode(String system, String code, String display, ValueSet vs);
300  public ValidationResult validateCode(Coding code, ValueSet vs);
301  public ValidationResult validateCode(CodeableConcept code, ValueSet vs);
302  
303  /**
304   * Validation of a code - consult the terminology service 
305   * to see whether it is known. If known, return a description of it
306   * Also, check whether it's in the provided value set fragment (for supported systems with no value set definition)
307   * 
308   * note: always return a result, with either an error or a code description, or both (e.g. known code, but not in the value set)
309   *  
310   * corresponds to 2 terminology service calls: $validate-code and $lookup
311   * 
312   * @param system
313   * @param code
314   * @param display
315   * @return
316   */
317  public ValidationResult validateCode(String system, String code, String display, ConceptSetComponent vsi);
318
319  /**
320   * returns the recommended tla for the type 
321   * 
322   * @param name
323   * @return
324   */
325  public String getAbbreviation(String name);
326
327  // return a set of types that have tails
328  public Set<String> typeTails();
329
330        public String oid2Uri(String code);
331
332  public StructureDefinition fetchTypeDefinition(String typeName);
333
334}