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