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