Package 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:

  • Field Details

  • Constructor Details

  • Method Details

    • 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:

    • getDefaultMfe5Type

      public String getDefaultMfe5Type()
      Returns the default datatype ("ST", "NM", etc) for an MFE segment with a missing MFE-5 value
      Returns:
      Returns the default datatype ("ST", "NM", etc) for an OBX segment with a missing MFE-5 value
      See Also:

    • getForcedEncode

      public Set<String> getForcedEncode()
      Returns:
      Returns the forced encode strings added by addForcedEncode(String)
      Since:
      1.3
      See Also:

    • 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:

    • getInvalidMfe5Type

      public String getInvalidMfe5Type()
      Returns the value provides a default datatype ("ST", "NM", etc) for an MFE segment with an invalid MFE-5 value.
      Returns:
      Returns the value provides a default datatype ("ST", "NM", etc) for an MFE segment with an invalid MFE-5 value.
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • removeForcedEncode

      public void removeForcedEncode(String theForcedEncode)
      Removes a forced encode entry
      Parameters:
      theForcedEncode - path definition to be removed
      Since:
      1.3
      See Also:

    • 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 FixFieldDataType.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:

    • setDefaultMfe5Type

      public void setDefaultMfe5Type(String theDefaultMfe5Type)

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

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

       MFE||||This is a value
      It will be parsed as though it had read: 
       MFE||||This is a value|ST

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

      Parameters:
      theDefaultMfe5Type - If this property is set, the value provides a default datatype ("ST", "NM", etc) for an MFE segment with a missing MFE-5 value
      See Also:

    • 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:

    • 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 FixFieldDataType.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:

    • setInvalidMfe5Type

      public void setInvalidMfe5Type(String theInvalidMfe5Type)

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

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

       MFE||||This is a value|INVALID
      It will be parsed as though it had read: 
       MFE||||This is a value|ST

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

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

    • 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