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 Summary

Constructors

Constructor and Description
Parser() Uses DefaultModelClassFactory for model class lookup.
Parser(HapiContext context) Creates a new parser, using the ModelClassFactory, the ParserConfiguration and the ValidationContext as defined in the context.
Parser(ModelClassFactory modelClassFactory) Initialize parser with custom ModelClassFactory and default ValidationContext

Method Summary

Modifier and Type	Method and Description
protected void	applySuperStructureName(Message theMessage)
static void	assertVersionExists(String version) Like validVersion(String) but throws an HL7Exception instead
protected abstract String	doEncode(Message source) Called by encode(Message) to perform implementation-specific encoding work.
protected abstract String	doEncode(Message source, String encoding) Called by encode(Message, String) to perform implementation-specific encoding work.
abstract String	doEncode(Segment structure, EncodingCharacters encodingCharacters) Encodes a particular segment and returns the encoded structure
abstract String	doEncode(Type type, EncodingCharacters encodingCharacters) Encodes a particular type and returns the encoded structure
protected abstract Message	doParse(String message, String version) Called by parse() to perform implementation-specific parsing work.
protected abstract Message	doParseForSpecificPackage(String message, String version, String packageName) Attempt the parse a message using a specific model package
String	encode(Message source) Formats a Message object into an HL7 message string using this parser's default encoding.
String	encode(Message source, String encoding) Formats a Message object into an HL7 message string using the given encoding.
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).
abstract Segment	getCriticalResponseData(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 String	getDefaultEncoding()
abstract String	getEncoding(String message) Returns a String representing the encoding of the given message, if the encoding is recognized.
ModelClassFactory	getFactory()
String	getMessageStructureForEvent(String name, String version) Deprecated. use ModelClassFactory.getMessageStructureForEvent(String, Version)
ParserConfiguration	getParserConfiguration() Returns the parser configuration.
ValidationContext	getValidationContext()
abstract String	getVersion(String message) Returns the version ID (MSH-12) from the given message, without fully parsing the message.
protected Message	instantiateMessage(String theName, String theVersion, boolean isExplicit) Note that the validation context of the resulting message is set to this parser's validation context.
protected Message	instantiateMessageInASpecificPackage(String theName, String theVersion, boolean isExplicit, String packageName) Instantiate a message type using a specific package name
static Segment	makeControlMSH(String version, ModelClassFactory factory) Creates a version-specific MSH object and returns it as a version-independent MSH interface.
abstract void	parse(Message message, String string) Parses a particular message and returns the encoded structure
abstract void	parse(Segment segment, String string, EncodingCharacters encodingCharacters) Parses a particular segment and returns the encoded structure
Message	parse(String message) Parses a message string and returns the corresponding Message object.
abstract void	parse(Type type, String string, EncodingCharacters encodingCharacters) Parses a particular type and returns the encoded structure
Message	parseForSpecificPackage(String message, String packageName) Parse a message using a specific model package instead of the default, using ModelClassFactory.getMessageClassInASpecificPackage(String, String, boolean, String) .
void	setParserConfiguration(ParserConfiguration configuration) Deprecated. use a dedicated HapiContext and set its ParserConfiguration property
void	setValidationContext(ValidationContext context) Deprecated. use a dedicated HapiContext and set its ValidationContext property
boolean	supportsEncoding(String encoding) Returns true if and only if the given encoding is supported by this Parser.
static boolean	validVersion(String version) Deprecated. Use Version.supportsVersion(String)

Methods inherited from class ca.uhn.hl7v2.HapiContextSupport

getHapiContext, setHapiContext

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

ModelClassFactory.getMessageClassInASpecificPackage(String, String, boolean, String)

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