001package ca.uhn.fhir.parser; 002 003/* 004 * #%L 005 * HAPI FHIR - Core Library 006 * %% 007 * Copyright (C) 2014 - 2020 University Health Network 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 023import ca.uhn.fhir.context.ConfigurationException; 024import ca.uhn.fhir.context.FhirContext; 025import ca.uhn.fhir.context.ParserOptions; 026import ca.uhn.fhir.model.api.IResource; 027import ca.uhn.fhir.rest.api.EncodingEnum; 028import org.hl7.fhir.instance.model.api.IAnyResource; 029import org.hl7.fhir.instance.model.api.IBaseResource; 030import org.hl7.fhir.instance.model.api.IIdType; 031 032import java.io.IOException; 033import java.io.InputStream; 034import java.io.Reader; 035import java.io.Writer; 036import java.util.Collection; 037import java.util.List; 038import java.util.Set; 039 040/** 041 * A parser, which can be used to convert between HAPI FHIR model/structure objects, and their respective String wire 042 * formats, in either XML or JSON. 043 * <p> 044 * Thread safety: <b>Parsers are not guaranteed to be thread safe</b>. Create a new parser instance for every thread or 045 * every message being parsed/encoded. 046 * </p> 047 */ 048public interface IParser { 049 050 String encodeResourceToString(IBaseResource theResource) throws DataFormatException; 051 052 void encodeResourceToWriter(IBaseResource theResource, Writer theWriter) throws IOException, DataFormatException; 053 054 /** 055 * If not set to null (as is the default) this ID will be used as the ID in any 056 * resources encoded by this parser 057 */ 058 IIdType getEncodeForceResourceId(); 059 060 /** 061 * Which encoding does this parser instance produce? 062 */ 063 EncodingEnum getEncoding(); 064 065 /** 066 * Gets the preferred types, as set using {@link #setPreferTypes(List)} 067 * 068 * @return Returns the preferred types, or <code>null</code> 069 * @see #setPreferTypes(List) 070 */ 071 List<Class<? extends IBaseResource>> getPreferTypes(); 072 073 /** 074 * Returns true if resource IDs should be omitted 075 * 076 * @see #setOmitResourceId(boolean) 077 * @since 1.1 078 */ 079 boolean isOmitResourceId(); 080 081 /** 082 * If set to <code>true<code> (which is the default), resource references containing a version 083 * will have the version removed when the resource is encoded. This is generally good behaviour because 084 * in most situations, references from one resource to another should be to the resource by ID, not 085 * by ID and version. In some cases though, it may be desirable to preserve the version in resource 086 * links. In that case, this value should be set to <code>false</code>. 087 * 088 * @return Returns the parser instance's configuration setting for stripping versions from resource references when 089 * encoding. This method will retun <code>null</code> if no value is set, in which case 090 * the value from the {@link ParserOptions} will be used (default is <code>true</code>) 091 * @see ParserOptions 092 */ 093 Boolean getStripVersionsFromReferences(); 094 095 /** 096 * Is the parser in "summary mode"? See {@link #setSummaryMode(boolean)} for information 097 * 098 * @see {@link #setSummaryMode(boolean)} for information 099 */ 100 boolean isSummaryMode(); 101 102 /** 103 * Parses a resource 104 * 105 * @param theResourceType 106 * The resource type to use. This can be used to explicitly specify a class which extends a built-in type 107 * (e.g. a custom type extending the default Patient class) 108 * @param theReader 109 * The reader to parse input from. Note that the Reader will not be closed by the parser upon completion. 110 * @return A parsed resource 111 * @throws DataFormatException 112 * If the resource can not be parsed because the data is not recognized or invalid for any reason 113 */ 114 <T extends IBaseResource> T parseResource(Class<T> theResourceType, Reader theReader) throws DataFormatException; 115 116 /** 117 * Parses a resource 118 * 119 * @param theResourceType 120 * The resource type to use. This can be used to explicitly specify a class which extends a built-in type 121 * (e.g. a custom type extending the default Patient class) 122 * @param theInputStream 123 * The InputStream to parse input from, <b>with an implied charset of UTF-8</b>. Note that the InputStream will not be closed by the parser upon completion. 124 * @return A parsed resource 125 * @throws DataFormatException 126 * If the resource can not be parsed because the data is not recognized or invalid for any reason 127 */ 128 <T extends IBaseResource> T parseResource(Class<T> theResourceType, InputStream theInputStream) throws DataFormatException; 129 130 /** 131 * Parses a resource 132 * 133 * @param theResourceType 134 * The resource type to use. This can be used to explicitly specify a class which extends a built-in type 135 * (e.g. a custom type extending the default Patient class) 136 * @param theString 137 * The string to parse 138 * @return A parsed resource 139 * @throws DataFormatException 140 * If the resource can not be parsed because the data is not recognized or invalid for any reason 141 */ 142 <T extends IBaseResource> T parseResource(Class<T> theResourceType, String theString) throws DataFormatException; 143 144 /** 145 * Parses a resource 146 * 147 * @param theReader 148 * The reader to parse input from. Note that the Reader will not be closed by the parser upon completion. 149 * @return A parsed resource. Note that the returned object will be an instance of {@link IResource} or 150 * {@link IAnyResource} depending on the specific FhirContext which created this parser. 151 * @throws DataFormatException 152 * If the resource can not be parsed because the data is not recognized or invalid for any reason 153 */ 154 IBaseResource parseResource(Reader theReader) throws ConfigurationException, DataFormatException; 155 156 /** 157 * Parses a resource 158 * 159 * @param theInputStream 160 * The InputStream to parse input from (charset is assumed to be UTF-8). 161 * Note that the stream will not be closed by the parser upon completion. 162 * @return A parsed resource. Note that the returned object will be an instance of {@link IResource} or 163 * {@link IAnyResource} depending on the specific FhirContext which created this parser. 164 * @throws DataFormatException 165 * If the resource can not be parsed because the data is not recognized or invalid for any reason 166 */ 167 IBaseResource parseResource(InputStream theInputStream) throws ConfigurationException, DataFormatException; 168 169 /** 170 * Parses a resource 171 * 172 * @param theMessageString 173 * The string to parse 174 * @return A parsed resource. Note that the returned object will be an instance of {@link IResource} or 175 * {@link IAnyResource} depending on the specific FhirContext which created this parser. 176 * @throws DataFormatException 177 * If the resource can not be parsed because the data is not recognized or invalid for any reason 178 */ 179 IBaseResource parseResource(String theMessageString) throws ConfigurationException, DataFormatException; 180 181 /** 182 * If provided, specifies the elements which should NOT be encoded. Valid values for this 183 * field would include: 184 * <ul> 185 * <li><b>Patient</b> - Don't encode patient and all its children</li> 186 * <li><b>Patient.name</b> - Don't encode the patient's name</li> 187 * <li><b>Patient.name.family</b> - Don't encode the patient's family name</li> 188 * <li><b>*.text</b> - Don't encode the text element on any resource (only the very first position may contain a 189 * wildcard)</li> 190 * </ul> 191 * <p> 192 * DSTU2 note: Note that values including meta, such as <code>Patient.meta</code> 193 * will work for DSTU2 parsers, but values with subelements on meta such 194 * as <code>Patient.meta.lastUpdated</code> will only work in 195 * DSTU3+ mode. 196 * </p> 197 * 198 * @param theDontEncodeElements 199 * The elements to encode 200 * @see #setEncodeElements(Set) 201 */ 202 IParser setDontEncodeElements(Set<String> theDontEncodeElements); 203 204 /** 205 * If provided, specifies the elements which should be encoded, to the exclusion of all others. Valid values for this 206 * field would include: 207 * <ul> 208 * <li><b>Patient</b> - Encode patient and all its children</li> 209 * <li><b>Patient.name</b> - Encode only the patient's name</li> 210 * <li><b>Patient.name.family</b> - Encode only the patient's family name</li> 211 * <li><b>*.text</b> - Encode the text element on any resource (only the very first position may contain a 212 * wildcard)</li> 213 * <li><b>*.(mandatory)</b> - This is a special case which causes any mandatory fields (min > 0) to be encoded</li> 214 * </ul> 215 * 216 * @param theEncodeElements 217 * The elements to encode 218 * @see #setDontEncodeElements(Set) 219 */ 220 IParser setEncodeElements(Set<String> theEncodeElements); 221 222 /** 223 * If set to <code>true</code> (default is false), the values supplied 224 * to {@link #setEncodeElements(Set)} will not be applied to the root 225 * resource (typically a Bundle), but will be applied to any sub-resources 226 * contained within it (i.e. search result resources in that bundle) 227 */ 228 void setEncodeElementsAppliesToChildResourcesOnly(boolean theEncodeElementsAppliesToChildResourcesOnly); 229 230 /** 231 * If set to <code>true</code> (default is false), the values supplied 232 * to {@link #setEncodeElements(Set)} will not be applied to the root 233 * resource (typically a Bundle), but will be applied to any sub-resources 234 * contained within it (i.e. search result resources in that bundle) 235 */ 236 boolean isEncodeElementsAppliesToChildResourcesOnly(); 237 238 /** 239 * When encoding, force this resource ID to be encoded as the resource ID 240 */ 241 IParser setEncodeForceResourceId(IIdType theForceResourceId); 242 243 /** 244 * If set to <code>true</code> (default is <code>false</code>) the ID of any resources being encoded will not be 245 * included in the output. Note that this does not apply to contained resources, only to root resources. In other 246 * words, if this is set to <code>true</code>, contained resources will still have local IDs but the outer/containing 247 * ID will not have an ID. 248 * 249 * @param theOmitResourceId 250 * Should resource IDs be omitted 251 * @return Returns a reference to <code>this</code> parser so that method calls can be chained together 252 * @since 1.1 253 */ 254 IParser setOmitResourceId(boolean theOmitResourceId); 255 256 /** 257 * Registers an error handler which will be invoked when any parse errors are found 258 * 259 * @param theErrorHandler 260 * The error handler to set. Must not be null. 261 */ 262 IParser setParserErrorHandler(IParserErrorHandler theErrorHandler); 263 264 /** 265 * If set, when parsing resources the parser will try to use the given types when possible, in 266 * the order that they are provided (from highest to lowest priority). For example, if a custom 267 * type which declares to implement the Patient resource is passed in here, and the 268 * parser is parsing a Bundle containing a Patient resource, the parser will use the given 269 * custom type. 270 * <p> 271 * This feature is related to, but not the same as the 272 * {@link FhirContext#setDefaultTypeForProfile(String, Class)} feature. 273 * <code>setDefaultTypeForProfile</code> is used to specify a type to be used 274 * when a resource explicitly declares support for a given profile. This 275 * feature specifies a type to be used irrespective of the profile declaration 276 * in the metadata statement. 277 * </p> 278 * 279 * @param thePreferTypes 280 * The preferred types, or <code>null</code> 281 */ 282 void setPreferTypes(List<Class<? extends IBaseResource>> thePreferTypes); 283 284 /** 285 * Sets the "pretty print" flag, meaning that the parser will encode resources with human-readable spacing and 286 * newlines between elements instead of condensing output as much as possible. 287 * 288 * @param thePrettyPrint 289 * The flag 290 * @return Returns an instance of <code>this</code> parser so that method calls can be chained together 291 */ 292 IParser setPrettyPrint(boolean thePrettyPrint); 293 294 /** 295 * Sets the server's base URL used by this parser. If a value is set, resource references will be turned into 296 * relative references if they are provided as absolute URLs but have a base matching the given base. 297 * 298 * @param theUrl 299 * The base URL, e.g. "http://example.com/base" 300 * @return Returns an instance of <code>this</code> parser so that method calls can be chained together 301 */ 302 IParser setServerBaseUrl(String theUrl); 303 304 /** 305 * If set to <code>true<code> (which is the default), resource references containing a version 306 * will have the version removed when the resource is encoded. This is generally good behaviour because 307 * in most situations, references from one resource to another should be to the resource by ID, not 308 * by ID and version. In some cases though, it may be desirable to preserve the version in resource 309 * links. In that case, this value should be set to <code>false</code>. 310 * <p> 311 * This method provides the ability to globally disable reference encoding. If finer-grained 312 * control is needed, use {@link #setDontStripVersionsFromReferencesAtPaths(String...)} 313 * </p> 314 * 315 * @param theStripVersionsFromReferences 316 * Set this to <code>false<code> to prevent the parser from removing resource versions from references (or <code>null</code> to apply the default setting from the {@link ParserOptions} 317 * @see #setDontStripVersionsFromReferencesAtPaths(String...) 318 * @see ParserOptions 319 * @return Returns a reference to <code>this</code> parser so that method calls can be chained together 320 */ 321 IParser setStripVersionsFromReferences(Boolean theStripVersionsFromReferences); 322 323 /** 324 * If set to <code>true</code> (which is the default), the Bundle.entry.fullUrl will override the Bundle.entry.resource's 325 * resource id if the fullUrl is defined. This behavior happens when parsing the source data into a Bundle object. Set this 326 * to <code>false</code> if this is not the desired behavior (e.g. the client code wishes to perform additional 327 * validation checks between the fullUrl and the resource id). 328 * 329 * @param theOverrideResourceIdWithBundleEntryFullUrl 330 * Set this to <code>false</code> to prevent the parser from overriding resource ids with the 331 * Bundle.entry.fullUrl (or <code>null</code> to apply the default setting from the {@link ParserOptions}) 332 * 333 * @see ParserOptions 334 * 335 * @return Returns a reference to <code>this</code> parser so that method calls can be chained together 336 */ 337 IParser setOverrideResourceIdWithBundleEntryFullUrl(Boolean theOverrideResourceIdWithBundleEntryFullUrl); 338 339 /** 340 * If set to <code>true</code> (default is <code>false</code>) only elements marked by the FHIR specification as 341 * being "summary elements" will be included. 342 * 343 * @return Returns a reference to <code>this</code> parser so that method calls can be chained together 344 */ 345 IParser setSummaryMode(boolean theSummaryMode); 346 347 /** 348 * If set to <code>true</code> (default is <code>false</code>), narratives will not be included in the encoded 349 * values. 350 */ 351 IParser setSuppressNarratives(boolean theSuppressNarratives); 352 353 /** 354 * If supplied value(s), any resource references at the specified paths will have their 355 * resource versions encoded instead of being automatically stripped during the encoding 356 * process. This setting has no effect on the parsing process. 357 * <p> 358 * This method provides a finer-grained level of control than {@link #setStripVersionsFromReferences(Boolean)} 359 * and any paths specified by this method will be encoded even if {@link #setStripVersionsFromReferences(Boolean)} 360 * has been set to <code>true</code> (which is the default) 361 * </p> 362 * 363 * @param thePaths 364 * A collection of paths for which the resource versions will not be removed automatically 365 * when serializing, e.g. "Patient.managingOrganization" or "AuditEvent.object.reference". Note that 366 * only resource name and field names with dots separating is allowed here (no repetition 367 * indicators, FluentPath expressions, etc.). Set to <code>null</code> to use the value 368 * set in the {@link ParserOptions} 369 * @see #setStripVersionsFromReferences(Boolean) 370 * @see ParserOptions 371 * @return Returns a reference to <code>this</code> parser so that method calls can be chained together 372 */ 373 IParser setDontStripVersionsFromReferencesAtPaths(String... thePaths); 374 375 /** 376 * If supplied value(s), any resource references at the specified paths will have their 377 * resource versions encoded instead of being automatically stripped during the encoding 378 * process. This setting has no effect on the parsing process. 379 * <p> 380 * This method provides a finer-grained level of control than {@link #setStripVersionsFromReferences(Boolean)} 381 * and any paths specified by this method will be encoded even if {@link #setStripVersionsFromReferences(Boolean)} 382 * has been set to <code>true</code> (which is the default) 383 * </p> 384 * 385 * @param thePaths 386 * A collection of paths for which the resource versions will not be removed automatically 387 * when serializing, e.g. "Patient.managingOrganization" or "AuditEvent.object.reference". Note that 388 * only resource name and field names with dots separating is allowed here (no repetition 389 * indicators, FluentPath expressions, etc.). Set to <code>null</code> to use the value 390 * set in the {@link ParserOptions} 391 * @see #setStripVersionsFromReferences(Boolean) 392 * @see ParserOptions 393 * @return Returns a reference to <code>this</code> parser so that method calls can be chained together 394 */ 395 IParser setDontStripVersionsFromReferencesAtPaths(Collection<String> thePaths); 396 397 /** 398 * Returns the value supplied to {@link IParser#setDontStripVersionsFromReferencesAtPaths(String...)} 399 * or <code>null</code> if no value has been set for this parser (in which case the default from 400 * the {@link ParserOptions} will be used} 401 * 402 * @see #setDontStripVersionsFromReferencesAtPaths(String...) 403 * @see #setStripVersionsFromReferences(Boolean) 404 * @see ParserOptions 405 */ 406 Set<String> getDontStripVersionsFromReferencesAtPaths(); 407 408}