ca.uhn.fhir.parser

Interface IParser

All Known Implementing Classes:

BaseParser, JsonParser, XmlParser

public interface IParser

A parser, which can be used to convert between HAPI FHIR model/structure objects, and their respective String wire formats, in either XML or JSON.

Thread safety: Parsers are not guaranteed to be thread safe. Create a new parser instance for every thread or every message being parsed/encoded.

Method Summary

Modifier and Type	Method and Description
String	encodeBundleToString(Bundle theBundle)
void	encodeBundleToWriter(Bundle theBundle, Writer theWriter)
String	encodeResourceToString(IBaseResource theResource)
void	encodeResourceToWriter(IBaseResource theResource, Writer theWriter)
String	encodeTagListToString(TagList theTagList) Encodes a tag list, as defined in the FHIR Specification.
void	encodeTagListToWriter(TagList theTagList, Writer theWriter) Encodes a tag list, as defined in the FHIR Specification.
Set<String>	getEncodeElements() See setEncodeElements(Set)
Set<String>	getEncodeElementsAppliesToResourceTypes() See setEncodeElementsAppliesToResourceTypes(Set)
EncodingEnum	getEncoding() Which encoding does this parser instance produce?
boolean	isOmitResourceId() Returns true if resource IDs should be omitted
boolean	isStripVersionsFromReferences() If set to true (which is the default), resource references containing a version will have the version removed when the resource is encoded.
boolean	isSummaryMode() Is the parser in "summary mode"? See setSummaryMode(boolean) for information
<T extends IBaseResource> Bundle	parseBundle(Class<T> theResourceType, Reader theReader) Parse a DSTU1 style Atom Bundle.
Bundle	parseBundle(Reader theReader) Parse a DSTU1 style Atom Bundle.
Bundle	parseBundle(String theMessageString) Parse a DSTU1 style Atom Bundle.
<T extends IBaseResource> T	parseResource(Class<T> theResourceType, Reader theReader) Parses a resource
<T extends IBaseResource> T	parseResource(Class<T> theResourceType, String theString) Parses a resource
IBaseResource	parseResource(Reader theReader) Parses a resource
IBaseResource	parseResource(String theMessageString) Parses a resource
TagList	parseTagList(Reader theReader) Parses a tag list, as defined in the FHIR Specification.
TagList	parseTagList(String theString) Parses a tag list, as defined in the FHIR Specification.
void	setEncodeElements(Set<String> theEncodeElements) If provided, specifies the elements which should be encoded, to the exclusion of all others.
void	setEncodeElementsAppliesToResourceTypes(Set<String> theEncodeElementsAppliesToResourceTypes) If provided, tells the parse which resource types to apply encode elements to.
IParser	setOmitResourceId(boolean theOmitResourceId) If set to true (default is false) the ID of any resources being encoded will not be included in the output.
IParser	setParserErrorHandler(IParserErrorHandler theErrorHandler) Registers an error handler which will be invoked when any parse errors are found
IParser	setPrettyPrint(boolean thePrettyPrint) Sets the "pretty print" flag, meaning that the parser will encode resources with human-readable spacing and newlines between elements instead of condensing output as much as possible.
IParser	setServerBaseUrl(String theUrl) Sets the server's base URL used by this parser.
IParser	setStripVersionsFromReferences(boolean theStripVersionsFromReferences) If set to true (which is the default), resource references containing a version will have the version removed when the resource is encoded.
IParser	setSummaryMode(boolean theSummaryMode) If set to true (default is false) only elements marked by the FHIR specification as being "summary elements" will be included.
IParser	setSuppressNarratives(boolean theSuppressNarratives) If set to true (default is false), narratives will not be included in the encoded values.

Method Detail

encodeBundleToString

String encodeBundleToString(Bundle theBundle)
                     throws DataFormatException

Throws:

DataFormatException

encodeBundleToWriter

void encodeBundleToWriter(Bundle theBundle,
                          Writer theWriter)
                   throws IOException,
                          DataFormatException

Throws:

IOException

DataFormatException

encodeResourceToString

String encodeResourceToString(IBaseResource theResource)
                       throws DataFormatException

Throws:

DataFormatException

encodeResourceToWriter

void encodeResourceToWriter(IBaseResource theResource,
                            Writer theWriter)
                     throws IOException,
                            DataFormatException

Throws:

IOException

DataFormatException

encodeTagListToString

String encodeTagListToString(TagList theTagList)

Encodes a tag list, as defined in the FHIR Specification.

Parameters:

theTagList - The tag list to encode. Must not be null.

Returns:

An encoded tag list

encodeTagListToWriter

void encodeTagListToWriter(TagList theTagList,
                           Writer theWriter)
                    throws IOException

Encodes a tag list, as defined in the FHIR Specification.

Parameters:

theTagList - The tag list to encode. Must not be null.

theWriter - The writer to encode to

Throws:

IOException

getEncodeElements

Set<String> getEncodeElements()

See setEncodeElements(Set)

getEncodeElementsAppliesToResourceTypes

Set<String> getEncodeElementsAppliesToResourceTypes()

See setEncodeElementsAppliesToResourceTypes(Set)

isOmitResourceId

boolean isOmitResourceId()

Returns true if resource IDs should be omitted

Since:

1.1

See Also:

setOmitResourceId(boolean)

isStripVersionsFromReferences

boolean isStripVersionsFromReferences()

If set to true (which is the default), resource references containing a version will have the version removed when the resource is encoded. This is generally good behaviour because in most situations, references from one resource to another should be to the resource by ID, not by ID and version. In some cases though, it may be desirable to preserve the version in resource links. In that case, this value should be set to false.

Returns:

Returns the parser instance's configuration setting for stripping versions from resource references when encoding. Default is true.

isSummaryMode

boolean isSummaryMode()

Is the parser in "summary mode"? See setSummaryMode(boolean) for information

See Also:

#setSummaryMode(boolean)} for information

parseBundle

<T extends IBaseResource> Bundle parseBundle(Class<T> theResourceType,
                                             Reader theReader)

Parse a DSTU1 style Atom Bundle. Note that as of DSTU2, Bundle is a resource so you should use parseResource(Class, Reader) with the Bundle class found in the ca.uhn.hapi.fhir.model.[version].resource package instead.

parseBundle

Bundle parseBundle(Reader theReader)

Parse a DSTU1 style Atom Bundle. Note that as of DSTU2, Bundle is a resource so you should use parseResource(Class, Reader) with the Bundle class found in the ca.uhn.hapi.fhir.model.[version].resource package instead.

parseBundle

Bundle parseBundle(String theMessageString)
            throws ConfigurationException,
                   DataFormatException

Parse a DSTU1 style Atom Bundle. Note that as of DSTU2, Bundle is a resource so you should use parseResource(Class, String) with the Bundle class found in the ca.uhn.hapi.fhir.model.[version].resource package instead.

Throws:

ConfigurationException

DataFormatException

parseResource

<T extends IBaseResource> T parseResource(Class<T> theResourceType,
                                          Reader theReader)
                                   throws DataFormatException

Parses a resource

Parameters:

theResourceType - The resource type to use. This can be used to explicitly specify a class which extends a built-in type (e.g. a custom type extending the default Patient class)

theReader - The reader to parse input from. Note that the Reader will not be closed by the parser upon completion.

Returns:

A parsed resource

Throws:

DataFormatException - If the resource can not be parsed because the data is not recognized or invalid for any reason

parseResource

<T extends IBaseResource> T parseResource(Class<T> theResourceType,
                                          String theString)
                                   throws DataFormatException

Parses a resource

Parameters:

theResourceType - The resource type to use. This can be used to explicitly specify a class which extends a built-in type (e.g. a custom type extending the default Patient class)

theString - The string to parse

Returns:

A parsed resource

Throws:

DataFormatException - If the resource can not be parsed because the data is not recognized or invalid for any reason

parseResource

IBaseResource parseResource(Reader theReader)
                     throws ConfigurationException,
                            DataFormatException

Parses a resource

Parameters:

theReader - The reader to parse input from. Note that the Reader will not be closed by the parser upon completion.

Returns:

A parsed resource. Note that the returned object will be an instance of IResource or IAnyResource depending on the specific FhirContext which created this parser.

Throws:

DataFormatException - If the resource can not be parsed because the data is not recognized or invalid for any reason

ConfigurationException

parseResource

IBaseResource parseResource(String theMessageString)
                     throws ConfigurationException,
                            DataFormatException

Parses a resource

Parameters:

theMessageString - The string to parse

Returns:

A parsed resource. Note that the returned object will be an instance of IResource or IAnyResource depending on the specific FhirContext which created this parser.

Throws:

DataFormatException - If the resource can not be parsed because the data is not recognized or invalid for any reason

ConfigurationException

parseTagList

TagList parseTagList(Reader theReader)

Parses a tag list, as defined in the FHIR Specification.

Parameters:

theReader - A reader which will supply a tag list

Returns:

A parsed tag list

parseTagList

TagList parseTagList(String theString)

Parses a tag list, as defined in the FHIR Specification.

Parameters:

theString - A string containing a tag list

Returns:

A parsed tag list

setEncodeElements

void setEncodeElements(Set<String> theEncodeElements)

If provided, specifies the elements which should be encoded, to the exclusion of all others. Valid values for this field would include:

• Patient - Encode patient and all its children
• Patient.name - Encoding only the patient's name
• Patient.name.family - Encode only the patient's family name
• *.text - Encode the text element on any resource (only the very first position may contain a wildcard)

Parameters:

theEncodeElements - The elements to encode

setEncodeElementsAppliesToResourceTypes

void setEncodeElementsAppliesToResourceTypes(Set<String> theEncodeElementsAppliesToResourceTypes)

If provided, tells the parse which resource types to apply encode elements to. Any resource types not specified here will be encoded completely, with no elements excluded.

Parameters:

theEncodeElementsAppliesToResourceTypes -

setOmitResourceId

IParser setOmitResourceId(boolean theOmitResourceId)

If set to true (default is false) the ID of any resources being encoded will not be included in the output. Note that this does not apply to contained resources, only to root resources. In other words, if this is set to true, contained resources will still have local IDs but the outer/containing ID will not have an ID.

Parameters:

theOmitResourceId - Should resource IDs be omitted

Returns:

Returns a reference to this parser so that method calls can be chained together

Since:

1.1

setParserErrorHandler

IParser setParserErrorHandler(IParserErrorHandler theErrorHandler)

Registers an error handler which will be invoked when any parse errors are found

Parameters:

theErrorHandler - The error handler to set. Must not be null.

setPrettyPrint

IParser setPrettyPrint(boolean thePrettyPrint)

Sets the "pretty print" flag, meaning that the parser will encode resources with human-readable spacing and newlines between elements instead of condensing output as much as possible.

Parameters:

thePrettyPrint - The flag

Returns:

Returns an instance of this parser so that method calls can be chained together

setServerBaseUrl

IParser setServerBaseUrl(String theUrl)

Sets the server's base URL used by this parser. If a value is set, resource references will be turned into relative references if they are provided as absolute URLs but have a base matching the given base.

Parameters:

theUrl - The base URL, e.g. "http://example.com/base"

Returns:

Returns an instance of this parser so that method calls can be chained together

setStripVersionsFromReferences

IParser setStripVersionsFromReferences(boolean theStripVersionsFromReferences)

If set to true (which is the default), resource references containing a version will have the version removed when the resource is encoded. This is generally good behaviour because in most situations, references from one resource to another should be to the resource by ID, not by ID and version. In some cases though, it may be desirable to preserve the version in resource links. In that case, this value should be set to false.

Parameters:

theStripVersionsFromReferences - Set this to false to prevent the parser from removing resource versions from references.

Returns:

Returns a reference to this parser so that method calls can be chained together

setSummaryMode

IParser setSummaryMode(boolean theSummaryMode)

If set to true (default is false) only elements marked by the FHIR specification as being "summary elements" will be included.

Returns:

Returns a reference to this parser so that method calls can be chained together

setSuppressNarratives

IParser setSuppressNarratives(boolean theSuppressNarratives)

If set to true (default is false), narratives will not be included in the encoded values.

getEncoding

EncodingEnum getEncoding()

Which encoding does this parser instance produce?