ca.uhn.hl7v2.parser

Class ParserConfiguration

java.lang.Object

ca.uhn.hl7v2.parser.ParserConfiguration

public class ParserConfiguration
extends Object

Contains configuration which will be applied to any parsers which are a part of the given HAPI Context.

See Also:

HapiContext.getParserConfiguration()

Field Summary

Fields

Modifier and Type	Field and Description
static UnexpectedSegmentBehaviourEnum	DEFAULT_UNEXPECTED_SEGMENT_BEHAVIOUR

Constructor Summary

Constructors

Constructor and Description
ParserConfiguration()

Method Summary

Modifier and Type	Method and Description
void	addForcedEncode(String theForcedEncode) Forces the parser to encode certain segments/fields, even if they contain no content.
String	getDefaultObx2Type() Returns the default datatype ("ST", "NM", etc) for an OBX segment with a missing OBX-2 value
Escaping	getEscaping()
Set<String>	getForcedEncode()
IDGenerator	getIdGenerator()
String	getInvalidObx2Type() Returns the value provides a default datatype ("ST", "NM", etc) for an OBX segment with an invalid OBX-2 value.
UnexpectedSegmentBehaviourEnum	getUnexpectedSegmentBehaviour() Returns the behaviour to use when parsing a message and a nonstandard segment is found.
Set<String>	getXmlDisableWhitespaceTrimmingOnNodeNames()
boolean	isAllowUnknownVersions() If set to true (default is false) the parser will allow messages to parse, even if they contain a version which is not known to the parser.
boolean	isEncodeEmptyMandatorySegments() Returns true if empty segments should still be encoded if they are mandatory within their message structure.
boolean	isEscapeSubcomponentDelimiterInPrimitive() Returns code>true if subcomponent delimiters in OBX-5 shall be ignored.
boolean	isNonGreedyMode() Returns true if the parser should parse in non-greedy mode.
boolean	isPrettyPrintWhenEncodingXml() If set to true (which is the default), XML Parsers will attempt to pretty-print the XML they generate.
boolean	isValidating() Returns true if the parser validates using a configured ValidationContext.
boolean	isXmlDisableWhitespaceTrimmingOnAllNodes()
void	removeForcedEncode(String theForcedEncode) Removes a forced encode entry
void	setAllowUnknownVersions(boolean theAllowUnknownVersions) If set to true (default is false) the parser will allow messages to parse, even if they contain a version which is not known to the parser.
void	setDefaultObx2Type(String theDefaultObx2Type) If this property is set, the value provides a default datatype ("ST", "NM", etc) for an OBX segment with a missing OBX-2 value.
void	setEncodeEmptyMandatoryFirstSegments(boolean theEncodeEmptyMandatorySegments) If set to true (default is true), when encoding a group using the PipeParser where the first segment is required, but no data has been populated in that segment, the empty segment is now still encoded if needed as a blank segment in order to give parsers a hint about which group subsequent segments are in.
void	setEscapeSubcomponentDelimiterInPrimitive(boolean escapeSubcomponentDelimiterInPrimitive) Set to true if subcomponent delimiters in OBX-5 shall be ignored
void	setEscaping(Escaping escaping) Sets an escaping strategy
void	setIdGenerator(IDGenerator idGenerator)
void	setInvalidObx2Type(String theInvalidObx2Type) If this property is set, the value provides a default datatype ("ST", "NM", etc) for an OBX segment with an invalid OBX-2 value.
void	setNonGreedyMode(boolean theNonGreedyMode) If set to true (default is false), pipe parser will be put in non-greedy mode.
void	setPrettyPrintWhenEncodingXml(boolean thePrettyPrintWhenEncodingXml) If set to true (which is the default), XML Parsers will attempt to pretty-print the XML they generate.
void	setUnexpectedSegmentBehaviour(UnexpectedSegmentBehaviourEnum theUnexpectedSegmentBehaviour) Sets the behaviour to use when parsing a message and a nonstandard segment is found
void	setValidating(boolean validating) Determines whether the parser validates using a configured ValidationContext or not.
void	setXmlDisableWhitespaceTrimmingOnAllNodes(boolean theXmlDisableWhitespaceTrimmingOnAllNodes) Configures the XML Parser to treat all whitespace within text nodes as literal, meaning that line breaks, tabs, multiple spaces, etc.
void	setXmlDisableWhitespaceTrimmingOnNodeNames(Set<String> theXmlDisableWhitespaceTrimmingOnNodeNames) Configures the XML Parser to treat all whitespace within the given nodes as literal, meaning that line breaks, tabs, multiple spaces, etc.
void	setXmlDisableWhitespaceTrimmingOnNodeNames(String... theKeepAsOriginalNodes) Configures the XML Parser to treat all whitespace within the given nodes as literal, meaning that line breaks, tabs, multiple spaces, etc.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_UNEXPECTED_SEGMENT_BEHAVIOUR

public static final UnexpectedSegmentBehaviourEnum DEFAULT_UNEXPECTED_SEGMENT_BEHAVIOUR

Constructor Detail

ParserConfiguration

public ParserConfiguration()

Method Detail

addForcedEncode

public void addForcedEncode(String theForcedEncode)

Forces the parser to encode certain segments/fields, even if they contain no content. This method may be called multiple times with multiple path definitions, and each path definition contains the path to the segment or field which needs to be forced.

Path definitions are similar in format to Terser paths. They contain a slash-separated lookup path to reach a given segment, and optionally a field number. The following are examples of paths which could be added here, as well as the sample output for an otherwise empty ORU^R01 message:

Forced Encode Path	Encode Output
None (for illustration purposes)	MSH|^~\&|||||||ORU^R01^ORU_R01||T|2.4
PATIENT_RESULT/ORDER_OBSERVATION/ORC	MSH|^~\&|||||||ORU^R01^ORU_R01||T|2.4 ORC|
PATIENT_RESULT/ORDER_OBSERVATION/ORC-4	MSH|^~\&|||||||ORU^R01^ORU_R01||T|2.4 ORC||||
PATIENT_RESULT/ORDER_OBSERVATION/ORC-4-2	MSH|^~\&|||||||ORU^R01^ORU_R01||T|2.4 ORC||||^

While empty segments do not generally have any meaning according to HL7, this may be useful when transmitting to systems which rely on segments being received even if they have no content.

Note that this configuration item currently only applies to PipeParser

Parameters:

theForcedEncode - path definition

Since:

2.0

getDefaultObx2Type

public String getDefaultObx2Type()

Returns the default datatype ("ST", "NM", etc) for an OBX segment with a missing OBX-2 value

Returns:

Returns the default datatype ("ST", "NM", etc) for an OBX segment with a missing OBX-2 value

See Also:

setDefaultObx2Type(String)

getForcedEncode

public Set<String> getForcedEncode()

Returns:

Returns the forced encode strings added by addForcedEncode(String)

Since:

1.3

See Also:

addForcedEncode(String)

getIdGenerator

public IDGenerator getIdGenerator()

Returns:

the ID Generator to be used for generating IDs for new messages

getInvalidObx2Type

public String getInvalidObx2Type()

Returns the value provides a default datatype ("ST", "NM", etc) for an OBX segment with an invalid OBX-2 value.

Returns:

Returns the value provides a default datatype ("ST", "NM", etc) for an OBX segment with an invalid OBX-2 value.

See Also:

setInvalidObx2Type(String)

getUnexpectedSegmentBehaviour

public UnexpectedSegmentBehaviourEnum getUnexpectedSegmentBehaviour()

Returns the behaviour to use when parsing a message and a nonstandard segment is found. Default is DEFAULT_UNEXPECTED_SEGMENT_BEHAVIOUR

Returns:

the behaviour to use when a nonstandard egment is found

getXmlDisableWhitespaceTrimmingOnNodeNames

public Set<String> getXmlDisableWhitespaceTrimmingOnNodeNames()

See Also:

setXmlDisableWhitespaceTrimmingOnNodeNames(Set)

isAllowUnknownVersions

public boolean isAllowUnknownVersions()

If set to true (default is false) the parser will allow messages to parse, even if they contain a version which is not known to the parser. When operating in this mode, if a message arrives with an unknown version string, the parser will attempt to parse it using a Generic Message class instead of a specific HAPI structure class. Default is false.

Returns:

true if parsing messages with unknown versions is allowed

isEncodeEmptyMandatorySegments

public boolean isEncodeEmptyMandatorySegments()

Returns true if empty segments should still be encoded if they are mandatory within their message structure. Default is false.

Returns:

true if empty segments should still be encoded

See Also:

setEncodeEmptyMandatoryFirstSegments(boolean)

isEscapeSubcomponentDelimiterInPrimitive

public boolean isEscapeSubcomponentDelimiterInPrimitive()

Returns code>true if subcomponent delimiters in OBX-5 shall be ignored. Default is false.

Returns:

true if subcomponent delimiters in OBX-5 shall be ignored

isNonGreedyMode

public boolean isNonGreedyMode()

Returns true if the parser should parse in non-greedy mode. Default is false

See Also:

for an explanation of non-greedy mode

isPrettyPrintWhenEncodingXml

public boolean isPrettyPrintWhenEncodingXml()

If set to true (which is the default), XML Parsers will attempt to pretty-print the XML they generate. This means the messages will look nicer to humans, but may take up slightly more space/bandwidth.

isValidating

public boolean isValidating()

Returns true if the parser validates using a configured ValidationContext. Default is true.

Returns:

true if the parser validates using a configured ValidationContext

isXmlDisableWhitespaceTrimmingOnAllNodes

public boolean isXmlDisableWhitespaceTrimmingOnAllNodes()

See Also:

setXmlDisableWhitespaceTrimmingOnAllNodes(boolean)

removeForcedEncode

public void removeForcedEncode(String theForcedEncode)

Removes a forced encode entry

Parameters:

theForcedEncode - path definition to be removed

Since:

1.3

See Also:

addForcedEncode(String)

setAllowUnknownVersions

public void setAllowUnknownVersions(boolean theAllowUnknownVersions)

If set to true (default is false) the parser will allow messages to parse, even if they contain a version which is not known to the parser. When operating in this mode, if a message arrives with an unknown version string, the parser will attempt to parse it using a Generic Message class instead of a specific HAPI structure class.

Parameters:

theAllowUnknownVersions - true if parsing unknown versions shall be allowed

setDefaultObx2Type

public void setDefaultObx2Type(String theDefaultObx2Type)

If this property is set, the value provides a default datatype ("ST", "NM", etc) for an OBX segment with a missing OBX-2 value. This is useful when parsing messages from systems which do not correctly populate OBX-2.

For example, if this property is set to "ST", and the following OBX segment is encountered:

 OBX|||||This is a value
 

It will be parsed as though it had read:

 OBX||ST|||This is a value
 

Note that this configuration can also be set globally using the system property Varies.DEFAULT_OBX2_TYPE_PROP, but any value provided to ParserConfiguration takes priority over the system property.

Parameters:

theDefaultObx2Type - If this property is set, the value provides a default datatype ("ST", "NM", etc) for an OBX segment with a missing OBX-2 value

See Also:

setInvalidObx2Type(String), Varies.INVALID_OBX2_TYPE_PROP

setEncodeEmptyMandatoryFirstSegments

public void setEncodeEmptyMandatoryFirstSegments(boolean theEncodeEmptyMandatorySegments)

If set to true (default is true), when encoding a group using the PipeParser where the first segment is required, but no data has been populated in that segment, the empty segment is now still encoded if needed as a blank segment in order to give parsers a hint about which group subsequent segments are in. This helps to ensure that messages can be "round tripped", meaning that a message which is parsed, encoded, and then re-parsed should contain exactly the same structure from beginning to end.

For example, in an ORU^R01 message with a populated OBX segment, but no data in the mandatory OBR segment which begins the ORDER_OBSERVATION group the message would still contain an empty OBR segment when encoded:

        MSH|^~\&|REG|W|||201103230042||ORU^R01|32153168|P|2.5
        OBR|
        OBX||ST|||Value Data
 

Previously, the following encoding would have occurred, which would have incorrectly been parsed as having a custom OBX segment instead of having a normal ORDER_OBSERVATION group:

        MSH|^~\&|REG|W|||201103230042||ORU^R01|32153168|P|2.5
        OBX||ST|||Value Data
 

Parameters:

theEncodeEmptyMandatorySegments - If set to true (default is true), when encoding a group using the PipeParser where the first segment is required, but no data has been populated in that segment, the empty segment is now still encoded if needed as a blank segment in order to give parsers a hint about which group subsequent segments are in

setEscapeSubcomponentDelimiterInPrimitive

public void setEscapeSubcomponentDelimiterInPrimitive(boolean escapeSubcomponentDelimiterInPrimitive)

Set to true if subcomponent delimiters in OBX-5 shall be ignored

Parameters:

escapeSubcomponentDelimiterInPrimitive - boolean flag to enable or disable this behavior

setIdGenerator

public void setIdGenerator(IDGenerator idGenerator)

Parameters:

idGenerator - the IDGenerator to be used for generating IDs for new messages, preferable initialized using the methods described in IDGeneratorFactory.

See Also:

IDGenerator

setInvalidObx2Type

public void setInvalidObx2Type(String theInvalidObx2Type)

If this property is set, the value provides a default datatype ("ST", "NM", etc) for an OBX segment with an invalid OBX-2 value. This is useful when parsing messages from systems which do not correctly populate OBX-2.

For example, if this property is set to "ST", and the following OBX segment is encountered:

 OBX||INVALID|||This is a value
 

It will be parsed as though it had read:

 OBX||ST|||This is a value
 

Note that this configuration can also be set globally using the system property Varies.INVALID_OBX2_TYPE_PROP, but any value provided to ParserConfiguration takes priority over the system property.

Parameters:

theInvalidObx2Type - If this property is set, the value provides a default datatype ("ST", "NM", etc) for an OBX segment with an invalid OBX-2 value. This is useful when parsing messages from systems which do not correctly populate OBX-2.

See Also:

setDefaultObx2Type(String), Varies.DEFAULT_OBX2_TYPE_PROP

setNonGreedyMode

public void setNonGreedyMode(boolean theNonGreedyMode)

If set to true (default is false), pipe parser will be put in non-greedy mode. This setting applies only to Pipe Parsers and will have no effect on XML Parsers.

In non-greedy mode, if the message structure being parsed has an ambiguous choice of where to put a segment because there is a segment matching the current segment name in both a later position in the message, and in an earlier position as a part of a repeating group, the earlier position will be chosen.

This is perhaps best explained with an example. Consider the following structure:

 MSH
 GROUP_1 (start)
 {
    AAA
    BBB
    GROUP_2 (start)
    {
       AAA
    }
    GROUP_2 (end)
 }
 GROUP_1 (end)
 

For the above example, consider a message containing the following segments:
MSH
AAA
BBB
AAA

In this example, when the second AAA segment is encountered, there are two possible choices. It would be placed in GROUP_2, or it could be placed in a second repetition of GROUP_1. By default it will be placed in GROUP_2, but in non-greedy mode it will be put in a new repetition of GROUP_1.

This mode is useful for example when parsing OML^O21 messages containing multiple orders.

setPrettyPrintWhenEncodingXml

public void setPrettyPrintWhenEncodingXml(boolean thePrettyPrintWhenEncodingXml)

If set to true (which is the default), XML Parsers will attempt to pretty-print the XML they generate. This means the messages will look nicer to humans, but may take up slightly more space/bandwidth.

setUnexpectedSegmentBehaviour

public void setUnexpectedSegmentBehaviour(UnexpectedSegmentBehaviourEnum theUnexpectedSegmentBehaviour)

Sets the behaviour to use when parsing a message and a nonstandard segment is found

Parameters:

theUnexpectedSegmentBehaviour - behaviour to use when a nonstandard segment is found

setValidating

public void setValidating(boolean validating)

Determines whether the parser validates using a configured ValidationContext or not. This allows to disable message validation although a validation context is defined.

Parameters:

validating - true if parser shall validate, false if not

getEscaping

public Escaping getEscaping()

setEscaping

public void setEscaping(Escaping escaping)

Sets an escaping strategy

Parameters:

escaping - escaping strategy instance

setXmlDisableWhitespaceTrimmingOnAllNodes

public void setXmlDisableWhitespaceTrimmingOnAllNodes(boolean theXmlDisableWhitespaceTrimmingOnAllNodes)

Configures the XML Parser to treat all whitespace within text nodes as literal, meaning that line breaks, tabs, multiple spaces, etc. will be preserved. If set to true, any values passed to setXmlDisableWhitespaceTrimmingOnNodeNames(Set) will be superceded since all whitespace will be treated as literal.

Default is false

setXmlDisableWhitespaceTrimmingOnNodeNames

public void setXmlDisableWhitespaceTrimmingOnNodeNames(Set<String> theXmlDisableWhitespaceTrimmingOnNodeNames)

Configures the XML Parser to treat all whitespace within the given nodes as literal, meaning that line breaks, tabs, multiple spaces, etc. will be preserved. This method takes individual XML node names as arguments (e.g. "HD.2", or "TX.1").

Default is none

setXmlDisableWhitespaceTrimmingOnNodeNames

public void setXmlDisableWhitespaceTrimmingOnNodeNames(String... theKeepAsOriginalNodes)

Configures the XML Parser to treat all whitespace within the given nodes as literal, meaning that line breaks, tabs, multiple spaces, etc. will be preserved. This method takes individual XML node names as arguments (e.g. "HD.2", or "TX.1").

Default is none