Package ca.uhn.hl7v2.parser

Class Parser

java.lang.Object
ca.uhn.hl7v2.HapiContextSupport
ca.uhn.hl7v2.parser.Parser
Direct Known Subclasses:
GenericParser, PipeParser, XMLParser
public abstract class Parser extends HapiContextSupport
Parses HL7 message Strings into HL7 Message objects and encodes HL7 Message objects into HL7 message Strings.
Author:
Bryan Tripp (bryan_tripp@sourceforge.net), Christian Ohr

  • Constructor Details

    • Parser

      public Parser()
      Uses DefaultModelClassFactory for model class lookup.

    • Parser

      public Parser(HapiContext context)
      Creates a new parser, using the ModelClassFactory, the ParserConfiguration and the ValidationContext as defined in the context.
      Parameters:
      context - HapiContext

    • Parser

      public Parser(ModelClassFactory modelClassFactory)
      Initialize parser with custom ModelClassFactory and default ValidationContext
      Parameters:
      modelClassFactory - custom factory to use for model class lookup

  • Method Details

    • getFactory

      public ModelClassFactory getFactory()
      Returns:
      the factory used by this Parser for model class lookup

    • getValidationContext

      public ValidationContext getValidationContext()
      Returns:
      the set of validation rules that is applied to messages parsed or encoded by this parser. Note that this method may return null

    • setValidationContext

      public void setValidationContext(ValidationContext context)
      Deprecated.
      use a dedicated HapiContext and set its ValidationContext property
      Parameters:
      context - the set of validation rules to be applied to messages parsed or encoded by this parser (defaults to ValidationContextFactory.DefaultValidation)

    • getParserConfiguration

      public ParserConfiguration getParserConfiguration()

      Returns the parser configuration. This is a bean which contains configuration instructions relating to how a parser should be parsing or encoding messages it deals with.

      Note that the parser configuration comes from the HAPI Context. Changes to the configuration for one parser will affect all parsers which share the same context.

      Returns:
      the current parser configuration

    • setParserConfiguration

      public void setParserConfiguration(ParserConfiguration configuration)
      Deprecated.
      use a dedicated HapiContext and set its ParserConfiguration property
      Sets the parser configuration for this parser (may not be null). This is a bean which contains configuration instructions relating to how a parser should be parsing or encoding messages it deals with.
      Parameters:
      configuration - The parser configuration

    • getEncoding

      public abstract String getEncoding(String message)
      Returns a String representing the encoding of the given message, if the encoding is recognized. For example if the given message appears to be encoded using HL7 2.x XML rules then "XML" would be returned. If the encoding is not recognized then null is returned. That this method returns a specific encoding does not guarantee that the message is correctly encoded (e.g. well formed XML) - just that it is not encoded using any other encoding than the one returned. Returns null if the encoding is not recognized.
      Parameters:
      message - message string
      Returns:
      string representing the encoding of the given message, i.e. "XML" or "ER7"

    • supportsEncoding

      public boolean supportsEncoding(String encoding)
      Returns true if and only if the given encoding is supported by this Parser.
      Parameters:
      encoding - the encoding, "XML" or "ER7"
      Returns:
      true if this parser supports parsing message encoded this way

    • getDefaultEncoding

      public abstract String getDefaultEncoding()
      Returns:
      the preferred encoding of this Parser ("XML" or "ER7")

    • parse

      public Message parse(String message) throws HL7Exception
      Parses a message string and returns the corresponding Message object.
      Parameters:
      message - a String that contains an HL7 message
      Returns:
      a HAPI Message object parsed from the given String
      Throws:
      HL7Exception - if the message is not correctly formatted.
      EncodingNotSupportedException - if the message encoded is not supported by this parser.

    • doParse

      protected abstract Message doParse(String message, String version) throws HL7Exception
      Called by parse() to perform implementation-specific parsing work.
      Parameters:
      message - a String that contains an HL7 message
      version - the name of the HL7 version to which the message belongs (eg "2.5")
      Returns:
      a HAPI Message object parsed from the given String
      Throws:
      HL7Exception - if the message is not correctly formatted.
      EncodingNotSupportedException - if the message encoded is not supported by this parser.

    • encode

      public String encode(Message source, String encoding) throws HL7Exception
      Formats a Message object into an HL7 message string using the given encoding.
      Parameters:
      source - a Message object from which to construct an encoded message string
      encoding - the name of the HL7 encoding to use (eg "XML"; most implementations support only one encoding)
      Returns:
      the encoded message
      Throws:
      HL7Exception - if the data fields in the message do not permit encoding (e.g. required fields are null)
      EncodingNotSupportedException - if the requested encoding is not supported by this parser.

    • doEncode

      protected abstract String doEncode(Message source, String encoding) throws HL7Exception
      Called by encode(Message, String) to perform implementation-specific encoding work.
      Parameters:
      source - a Message object from which to construct an encoded message string
      encoding - the name of the HL7 encoding to use (eg "XML"; most implementations support only one encoding)
      Returns:
      the encoded message
      Throws:
      HL7Exception - if the data fields in the message do not permit encoding (e.g. required fields are null)
      EncodingNotSupportedException - if the requested encoding is not supported by this parser.

    • encode

      public String encode(Message source) throws HL7Exception
      Formats a Message object into an HL7 message string using this parser's default encoding.
      Parameters:
      source - a Message object from which to construct an encoded message string
      Returns:
      the encoded message
      Throws:
      HL7Exception - if the data fields in the message do not permit encoding (e.g. required fields are null)

    • doEncode

      protected abstract String doEncode(Message source) throws HL7Exception
      Called by encode(Message) to perform implementation-specific encoding work.
      Parameters:
      source - a Message object from which to construct an encoded message string
      Returns:
      the encoded message
      Throws:
      HL7Exception - if the data fields in the message do not permit encoding (e.g. required fields are null)
      EncodingNotSupportedException - if the requested encoding is not supported by this parser.

    • getCriticalResponseData

      public abstract Segment getCriticalResponseData(String message) throws HL7Exception

      Returns a minimal amount of data from a message string, including only the data needed to send a response to the remote system. This includes the following fields:

      • field separator
      • encoding characters
      • processing ID
      • message control ID
      This method is intended for use when there is an error parsing a message, (so the Message object is unavailable) but an error message must be sent back to the remote system including some of the information in the inbound message. This method parses only that required information, hopefully avoiding the condition that caused the original error.

      Parameters:
      message - the message
      Returns:
      an MSH segment
      Throws:
      HL7Exception - if no MSH segment could be created

    • getAckID

      public abstract String getAckID(String message)
      For response messages, returns the value of MSA-2 (the message ID of the message sent by the sending system). This value may be needed prior to main message parsing, so that (particularly in a multi-threaded scenario) the message can be routed to the thread that sent the request. We need this information first so that any parse exceptions are thrown to the correct thread. Implementers of Parsers should take care to make the implementation of this method very fast and robust. Returns null if MSA-2 can not be found (e.g. if the message is not a response message).
      Parameters:
      message - the message
      Returns:
      the value of MSA-2

    • getVersion

      public abstract String getVersion(String message) throws HL7Exception
      Returns the version ID (MSH-12) from the given message, without fully parsing the message. The version is needed prior to parsing in order to determine the message class into which the text of the message should be parsed.
      Parameters:
      message - the message
      Returns:
      the value of MSH-12
      Throws:
      HL7Exception - if the version field can not be found.

    • doEncode

      public abstract String doEncode(Segment structure, EncodingCharacters encodingCharacters) throws HL7Exception
      Encodes a particular segment and returns the encoded structure
      Parameters:
      structure - The structure to encode
      encodingCharacters - The encoding characters
      Returns:
      The encoded segment
      Throws:
      HL7Exception - If there is a problem encoding
      Since:
      1.0

    • doEncode

      public abstract String doEncode(Type type, EncodingCharacters encodingCharacters) throws HL7Exception
      Encodes a particular type and returns the encoded structure
      Parameters:
      type - The type to encode
      encodingCharacters - The encoding characters
      Returns:
      The encoded type
      Throws:
      HL7Exception - If there is a problem encoding
      Since:
      1.0

    • parse

      public abstract void parse(Type type, String string, EncodingCharacters encodingCharacters) throws HL7Exception
      Parses a particular type and returns the encoded structure
      Parameters:
      string - The string to parse
      type - The type to encode
      encodingCharacters - The encoding characters
      Throws:
      HL7Exception - If there is a problem encoding
      Since:
      1.0

    • parseForSpecificPackage

      public Message parseForSpecificPackage(String message, String packageName) throws HL7Exception
      Parse a message using a specific model package instead of the default, using ModelClassFactory.getMessageClassInASpecificPackage(String, String, boolean, String) . WARNING: This method is only implemented in some parser implementations. Currently it will only work with the PipeParser parser implementation. Use with caution.
      Parameters:
      message - message string
      packageName - name of the package of the models
      Returns:
      parsed message
      Throws:
      HL7Exception - if an error occurred while parsing

    • doParseForSpecificPackage

      protected abstract Message doParseForSpecificPackage(String message, String version, String packageName) throws HL7Exception
      Attempt the parse a message using a specific model package
      Throws:
      HL7Exception

    • instantiateMessageInASpecificPackage

      protected Message instantiateMessageInASpecificPackage(String theName, String theVersion, boolean isExplicit, String packageName) throws HL7Exception
      Instantiate a message type using a specific package name
      Throws:
      HL7Exception
      See Also:

    • parse

      public abstract void parse(Segment segment, String string, EncodingCharacters encodingCharacters) throws HL7Exception
      Parses a particular segment and returns the encoded structure
      Parameters:
      segment - The segment to encode
      string - The string to parse
      encodingCharacters - The encoding characters
      Throws:
      HL7Exception - If there is a problem encoding

    • parse

      public abstract void parse(Message message, String string) throws HL7Exception
      Parses a particular message and returns the encoded structure
      Parameters:
      message - The message to encode
      string - The string to parse
      Throws:
      HL7Exception - If there is a problem encoding
      Since:
      1.0

    • makeControlMSH

      public static Segment makeControlMSH(String version, ModelClassFactory factory) throws HL7Exception

      Creates a version-specific MSH object and returns it as a version-independent MSH interface.

      Since HAPI 2.1, if a version specific MSH segment can't be found (for example because the specific structure JAR is not found on the classpath), an instance of GenericSegment is returned.

      Parameters:
      version - HL7 version
      factory - model class factory to be used
      Returns:
      MSH segment for this version returned by the model class factory
      Throws:
      HL7Exception - if no matching segment could be found

    • validVersion

      @Deprecated public static boolean validVersion(String version)
      Deprecated.
      Use Version.supportsVersion(String)
      Returns true if the given string represents a valid 2.x version. Valid versions include "2.1", "2.2", "2.3", "2.3.1", "2.4", "2.5", "2.5.1", "2.6"
      Parameters:
      version - HL7 version string
      Returns:
      true if version is known

    • assertVersionExists

      public static void assertVersionExists(String version) throws HL7Exception
      Like validVersion(String) but throws an HL7Exception instead
      Parameters:
      version - HL7 version
      Throws:
      HL7Exception - if version is unknown

    • getMessageStructureForEvent

      public String getMessageStructureForEvent(String name, String version) throws HL7Exception
      Deprecated.
      use ModelClassFactory.getMessageStructureForEvent(String, Version)
      Given a concatenation of message type and event (e.g. ADT_A04), and the version, finds the corresponding message structure (e.g. ADT_A01). This is needed because some events share message structures, although it is not needed when the message structure is explicitly valued in MSH-9-3. If no mapping is found, returns the original name.
      Throws:
      HL7Exception - if there is an error retrieving the map, or if the given version is invalid

    • instantiateMessage

      protected Message instantiateMessage(String theName, String theVersion, boolean isExplicit) throws HL7Exception
      Note that the validation context of the resulting message is set to this parser's validation context. The validation context is used within Primitive.setValue().
      Parameters:
      theName - name of the desired structure in the form XXX_YYY
      theVersion - HL7 version (e.g. "2.3")
      isExplicit - true if the structure was specified explicitly in MSH-9-3, false if it was inferred from MSH-9-1 and MSH-9-2. If false, a lookup may be performed to find an alternate structure corresponding to that message type and event.
      Returns:
      a Message instance
      Throws:
      HL7Exception - if the version is not recognized or no appropriate class can be found or the Message class throws an exception on instantiation (e.g. if args are not as expected)

    • applySuperStructureName

      protected void applySuperStructureName(Message theMessage) throws HL7Exception
      Throws:
      HL7Exception