001package org.hl7.fhir.dstu2.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;
035
036import java.util.Locale;
037import org.hl7.fhir.dstu2.formats.IParser;
038import org.hl7.fhir.dstu2.formats.ParserType;
039import org.hl7.fhir.dstu2.model.CodeableConcept;
040import org.hl7.fhir.dstu2.model.Coding;
041import org.hl7.fhir.dstu2.model.ConceptMap;
042import org.hl7.fhir.dstu2.model.Resource;
043import org.hl7.fhir.dstu2.model.StructureDefinition;
044import org.hl7.fhir.dstu2.model.ValueSet;
045import org.hl7.fhir.dstu2.model.ValueSet.ConceptDefinitionComponent;
046import org.hl7.fhir.dstu2.model.ValueSet.ConceptSetComponent;
047import org.hl7.fhir.dstu2.model.ValueSet.ValueSetExpansionComponent;
048import org.hl7.fhir.dstu2.terminologies.ValueSetExpander.ValueSetExpansionOutcome;
049import org.hl7.fhir.dstu2.utils.validation.IResourceValidator;
050import org.hl7.fhir.utilities.validation.ValidationMessage.IssueSeverity;
051
052
053/**
054 * This is the standard interface used for access to underlying FHIR
055 * services through the tools and utilities provided by the reference
056 * implementation. 
057 * 
058 * The functionality it provides is 
059 *  - get access to parsers, validators, narrative builders etc
060 *    (you can't create these directly because they need access 
061 *    to the right context for their information)
062 *    
063 *  - find resources that the tools need to carry out their tasks
064 *  
065 *  - provide access to terminology services they need. 
066 *    (typically, these terminology service requests are just
067 *    passed through to the local implementation's terminology
068 *    service)    
069 *  
070 * @author Grahame
071 */
072public interface IWorkerContext {
073
074  // -- Parsers (read and write instances) ----------------------------------------
075
076  /**
077   * Get a parser to read/write instances. Use the defined type (will be extended 
078   * as further types are added, though the only currently anticipate type is RDF)
079   * 
080   * XML/JSON - the standard renderers
081   * XHTML - render the narrative only (generate it if necessary)
082   * 
083   * @param type
084   * @return
085   */
086  public IParser getParser(ParserType type);
087
088  /**
089   * Get a parser to read/write instances. Determine the type 
090   * from the stated type. Supported value for type:
091   * - the recommended MIME types
092   * - variants of application/xml and application/json
093   * - _format values xml, json
094   * 
095   * @param type
096   * @return
097   */   
098  public IParser getParser(String type);
099
100  /**
101   * Get a JSON parser
102   * 
103   * @return
104   */
105  public IParser newJsonParser();
106
107  /**
108   * Get an XML parser
109   * 
110   * @return
111   */
112  public IParser newXmlParser();
113
114  /**
115   * Get a generator that can generate narrative for the instance
116   * 
117   * @return a prepared generator
118   */
119  public INarrativeGenerator getNarrativeGenerator(String prefix, String basePath);
120
121  /**
122   * Get a validator that can check whether a resource is valid 
123   * 
124   * @return a prepared generator
125   * @
126   */
127  public IResourceValidator newValidator();
128
129  // -- resource fetchers ---------------------------------------------------
130
131  /**
132   * Find an identified resource. The most common use of this is to access the the 
133   * standard conformance resources that are part of the standard - structure 
134   * definitions, value sets, concept maps, etc.
135   * 
136   * Also, the narrative generator uses this, and may access any kind of resource
137   * 
138   * The URI is called speculatively for things that might exist, so not finding 
139   * a matching resouce, return null, not an error
140   * 
141   * The URI can have one of 3 formats:
142   *  - a full URL e.g. http://acme.org/fhir/ValueSet/[id]
143   *  - a relative URL e.g. ValueSet/[id]
144   *  - a logical id e.g. [id]
145   *  
146   * It's an error if the second form doesn't agree with class_. It's an 
147   * error if class_ is null for the last form
148   * 
149   * @param resource
150   * @param Reference
151   * @return
152   * @throws Exception
153   */
154  public <T extends Resource> T fetchResource(Class<T> class_, String uri);
155
156  /**
157   * find whether a resource is available. 
158   * 
159   * Implementations of the interface can assume that if hasResource ruturns 
160   * true, the resource will usually be fetched subsequently
161   * 
162   * @param class_
163   * @param uri
164   * @return
165   */
166  public <T extends Resource> boolean hasResource(Class<T> class_, String uri);
167
168  // -- profile services ---------------------------------------------------------
169  
170  public List<String> getResourceNames();
171  
172  // -- Terminology services ------------------------------------------------------
173
174  // these are the terminology services used internally by the tools
175  /**
176   * Find a value set for the nominated system uri. 
177   * return null if there isn't one (then the tool might try 
178   * supportsSystem)
179   * 
180   * @param system
181   * @return
182   */
183  public ValueSet fetchCodeSystem(String system);
184
185  /**
186   * True if the underlying terminology service provider will do 
187   * expansion and code validation for the terminology. Corresponds
188   * to the extension 
189   * 
190   * http://hl7.org/fhir/StructureDefinition/conformance-supported-system
191   * 
192   * in the Conformance resource
193   * 
194   * @param system
195   * @return
196   */
197  public boolean supportsSystem(String system);
198
199  /**
200   * find concept maps for a source
201   * @param url
202   * @return
203   */
204  public List<ConceptMap> findMapsForSource(String url);  
205
206  /**
207   * ValueSet Expansion - see $expand
208   *  
209   * @param source
210   * @return
211   */
212  public ValueSetExpansionOutcome expandVS(ValueSet source, boolean cacheOk);
213  
214  /**
215   * Value set expanion inside the internal expansion engine - used 
216   * for references to supported system (see "supportsSystem") for
217   * which there is no value set. 
218   * 
219   * @param inc
220   * @return
221   */
222  public ValueSetExpansionComponent expandVS(ConceptSetComponent inc);
223
224  Locale getLocale();
225
226  void setLocale(Locale locale);
227
228  String formatMessage(String theMessage, Object... theMessageArguments);
229
230  void setValidationMessageLanguage(Locale locale);
231
232  public class ValidationResult {
233    private ConceptDefinitionComponent definition;
234    private IssueSeverity severity;
235    private String message;
236    
237    public ValidationResult(IssueSeverity severity, String message) {
238      this.severity = severity;
239      this.message = message;
240    }
241    
242    public ValidationResult(ConceptDefinitionComponent definition) {
243      this.definition = definition;
244    }
245
246    public ValidationResult(IssueSeverity severity, String message, ConceptDefinitionComponent definition) {
247      this.severity = severity;
248      this.message = message;
249      this.definition = definition;
250    }
251    
252    public boolean isOk() {
253      return definition != null;
254    }
255
256    public String getDisplay() {
257      return definition == null ? "??" : definition.getDisplay();
258    }
259
260    public ConceptDefinitionComponent asConceptDefinition() {
261      return definition;
262    }
263
264    public IssueSeverity getSeverity() {
265      return severity;
266    }
267
268    public String getMessage() {
269      return message;
270    }
271  }
272
273  /**
274   * Validation of a code - consult the terminology service 
275   * to see whether it is known. If known, return a description of it
276   * 
277   *  note: always return a result, with either an error or a code description
278   *  
279   * corresponds to 2 terminology service calls: $validate-code and $lookup
280   * 
281   * @param system
282   * @param code
283   * @param display
284   * @return
285   */
286  public ValidationResult validateCode(String system, String code, String display);
287
288  /**
289   * Validation of a code - consult the terminology service 
290   * to see whether it is known. If known, return a description of it
291   * Also, check whether it's in the provided value set
292   * 
293   * 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)
294   *  
295   * corresponds to 2 terminology service calls: $validate-code and $lookup
296   * 
297   * @param system
298   * @param code
299   * @param display
300   * @return
301   */
302  public ValidationResult validateCode(String system, String code, String display, ValueSet vs);
303  public ValidationResult validateCode(Coding code, ValueSet vs);
304  public ValidationResult validateCode(CodeableConcept code, ValueSet vs);
305  
306  /**
307   * Validation of a code - consult the terminology service 
308   * to see whether it is known. If known, return a description of it
309   * Also, check whether it's in the provided value set fragment (for supported systems with no value set definition)
310   * 
311   * 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)
312   *  
313   * corresponds to 2 terminology service calls: $validate-code and $lookup
314   * 
315   * @param system
316   * @param code
317   * @param display
318   * @return
319   */
320  public ValidationResult validateCode(String system, String code, String display, ConceptSetComponent vsi);
321
322  /**
323   * returns the recommended tla for the type 
324   * 
325   * @param name
326   * @return
327   */
328  public String getAbbreviation(String name);
329
330  public List<StructureDefinition> allStructures();
331
332  public StructureDefinition fetchTypeDefinition(String typeName);
333
334}