
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}