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