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