ca.uhn.hl7v2.parser
Class Parser

java.lang.Object
  extended by ca.uhn.hl7v2.parser.Parser
Direct Known Subclasses:
FastParser, GenericParser, OldPipeParser, PipeParser, XMLParser

public abstract class Parser
extends java.lang.Object

Parses HL7 message Strings into HL7 Message objects and encodes HL7 Message objects into HL7 message Strings.

Author:
Bryan Tripp (bryan_tripp@sourceforge.net)

Constructor Summary
Parser()
          Uses DefaultModelClassFactory for model class lookup.
Parser(ModelClassFactory theFactory)
           
 
Method Summary
protected abstract  java.lang.String doEncode(Message source)
          Called by encode(Message) to perform implementation-specific encoding work.
protected abstract  java.lang.String doEncode(Message source, java.lang.String encoding)
          Called by encode(Message, String) to perform implementation-specific encoding work.
abstract  java.lang.String doEncode(Segment structure, EncodingCharacters encodingCharacters)
          Encodes a particular segment and returns the encoded structure
abstract  java.lang.String doEncode(Type type, EncodingCharacters encodingCharacters)
          Encodes a particular type and returns the encoded structure
protected abstract  Message doParse(java.lang.String message, java.lang.String version)
          Called by parse() to perform implementation-specific parsing work.
 java.lang.String encode(Message source)
          Formats a Message object into an HL7 message string using this parser's default encoding.
 java.lang.String encode(Message source, java.lang.String encoding)
          Formats a Message object into an HL7 message string using the given encoding.
abstract  java.lang.String getAckID(java.lang.String message)
          For response messages, returns the value of MSA-2 (the message ID of the message sent by the sending system).
abstract  Segment getCriticalResponseData(java.lang.String message)
          Returns a minimal amount of data from a message string, including only the data needed to send a response to the remote system.
abstract  java.lang.String getDefaultEncoding()
           
abstract  java.lang.String getEncoding(java.lang.String message)
          Returns a String representing the encoding of the given message, if the encoding is recognized.
 ModelClassFactory getFactory()
           
static java.lang.String getMessageStructureForEvent(java.lang.String name, java.lang.String version)
          Given a concatenation of message type and event (e.g.
static java.util.Properties getMessageStructures(java.lang.String version)
          Returns a copy of the message structure map for a specific version.
 ValidationContext getValidationContext()
           
static java.util.List<java.lang.String> getValidVersions()
           
abstract  java.lang.String getVersion(java.lang.String message)
          Returns the version ID (MSH-12) from the given message, without fully parsing the message.
protected  Message instantiateMessage(java.lang.String theName, java.lang.String theVersion, boolean isExplicit)
          Note that the validation context of the resulting message is set to this parser's validation context.
static Segment makeControlMSH(java.lang.String version, ModelClassFactory factory)
          Creates a version-specific MSH object and returns it as a version-independent MSH interface.
abstract  void parse(Message message, java.lang.String string)
          Parses a particular message and returns the encoded structure
abstract  void parse(Segment segment, java.lang.String string, EncodingCharacters encodingCharacters)
          Parses a particular segment and returns the encoded structure
 Message parse(java.lang.String message)
          Parses a message string and returns the corresponding Message object.
abstract  void parse(Type type, java.lang.String string, EncodingCharacters encodingCharacters)
          Parses a particular type and returns the encoded structure
 void setValidationContext(ValidationContext theContext)
           
abstract  boolean supportsEncoding(java.lang.String encoding)
          Returns true if and only if the given encoding is supported by this Parser.
static boolean validVersion(java.lang.String version)
          Returns true if the given string represents a valid 2.x version.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Parser

public Parser()
Uses DefaultModelClassFactory for model class lookup.


Parser

public Parser(ModelClassFactory theFactory)
Parameters:
theFactory - custom factory to use for model class lookup
Method Detail

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 theContext)
Parameters:
theContext - the set of validation rules to be applied to messages parsed or encoded by this parser (defaults to ValidationContextFactory.DefaultValidation)

getEncoding

public abstract java.lang.String getEncoding(java.lang.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.


supportsEncoding

public abstract boolean supportsEncoding(java.lang.String encoding)
Returns true if and only if the given encoding is supported by this Parser.


getDefaultEncoding

public abstract java.lang.String getDefaultEncoding()
Returns:
the preferred encoding of this Parser

parse

public Message parse(java.lang.String message)
              throws HL7Exception,
                     EncodingNotSupportedException
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(java.lang.String message,
                                   java.lang.String version)
                            throws HL7Exception,
                                   EncodingNotSupportedException
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 java.lang.String encode(Message source,
                               java.lang.String encoding)
                        throws HL7Exception,
                               EncodingNotSupportedException
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 java.lang.String doEncode(Message source,
                                             java.lang.String encoding)
                                      throws HL7Exception,
                                             EncodingNotSupportedException
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 java.lang.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
encoding - the name of the 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)

doEncode

protected abstract java.lang.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(java.lang.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:

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.

Returns:
an MSH segment
Throws:
HL7Exception

getAckID

public abstract java.lang.String getAckID(java.lang.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).


getVersion

public abstract java.lang.String getVersion(java.lang.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.

Throws:
HL7Exception - if the version field can not be found.

doEncode

public abstract java.lang.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 java.lang.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,
                           java.lang.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

parse

public abstract void parse(Segment segment,
                           java.lang.String string,
                           EncodingCharacters encodingCharacters)
                    throws HL7Exception
Parses a particular segment and returns the encoded structure

Parameters:
string - The string to parse
segment - The segment to encode
encodingCharacters - The encoding characters
Throws:
HL7Exception - If there is a problem encoding

parse

public abstract void parse(Message message,
                           java.lang.String string)
                    throws HL7Exception
Parses a particular message and returns the encoded structure

Parameters:
string - The string to parse
message - The message to encode
Throws:
HL7Exception - If there is a problem encoding
Since:
1.0

makeControlMSH

public static Segment makeControlMSH(java.lang.String version,
                                     ModelClassFactory factory)
                              throws HL7Exception
Creates a version-specific MSH object and returns it as a version-independent MSH interface. throws HL7Exception if there is a problem, e.g. invalid version, code not available for given version.

Throws:
HL7Exception

validVersion

public static boolean validVersion(java.lang.String version)
Returns true if the given string represents a valid 2.x version. Valid versions include "2.0", "2.0D", "2.1", "2.2", "2.3", "2.3.1", "2.4", "2.5", etc


getValidVersions

public static java.util.List<java.lang.String> getValidVersions()
Returns:
A list of strings containing the valid versions of HL7 supported by HAPI ("2.1", "2.2", etc)

getMessageStructureForEvent

public static java.lang.String getMessageStructureForEvent(java.lang.String name,
                                                           java.lang.String version)
                                                    throws HL7Exception
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

getMessageStructures

public static java.util.Properties getMessageStructures(java.lang.String version)
                                                 throws java.io.IOException
Returns a copy of the message structure map for a specific version. Each key is a message type (e.g. ADT_A04) and each value is the corresponding structure (e.g. ADT_A01).

Throws:
java.io.IOException - If the event map can't be loaded

instantiateMessage

protected Message instantiateMessage(java.lang.String theName,
                                     java.lang.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:
name - name of the desired structure in the form XXX_YYY
version - 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)


Copyright © 2001-2011 University Health Network. All Rights Reserved.