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