ca.uhn.hl7v2.parser

Class PipeParser

java.lang.Object

ca.uhn.hl7v2.HapiContextSupport

ca.uhn.hl7v2.parser.Parser

ca.uhn.hl7v2.parser.PipeParser

public class PipeParser
extends Parser

An implementation of Parser that supports traditionally encoded (ie delimited with characters like |, ^, and ~) HL7 messages. Unexpected segments and fields are parsed into generic elements that are added to the message.

Author:

Bryan Tripp (bryan_tripp@sourceforge.net)

See Also:

for configuration options which may affect parser encoding and decoding behaviour

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_LEGACY_MODE_PROPERTY Deprecated. This will be removed in HAPI 3.0

Constructor Summary

Constructors

Constructor and Description
PipeParser()
PipeParser(HapiContext context)
PipeParser(ModelClassFactory theFactory) Creates a new PipeParser

Method Summary

Modifier and Type	Method and Description
protected String	doEncode(Message source) Formats a Message object into an HL7 message string using this parser's default encoding ("VB").
protected String	doEncode(Message source, String encoding) Formats a Message object into an HL7 message string using the given encoding.
String	doEncode(Segment structure, EncodingCharacters encodingCharacters) Encodes a particular segment and returns the encoded structure
String	doEncode(Type type, EncodingCharacters encodingCharacters) Encodes a particular type and returns the encoded structure
protected Message	doParse(String message, String version) Parses a message string and returns the corresponding Message object.
protected Message	doParseForSpecificPackage(String message, String version, String packageName) Attempt the parse a message using a specific model package
static String	encode(Group source, EncodingCharacters encodingChars) Returns given group serialized as a pipe-encoded string - this method is called by encode(Message source, String encoding).
String	encode(Message source) Formats a Message object into an HL7 message string using this parser's default encoding.
static String	encode(Segment source, EncodingCharacters encodingChars) Returns given segment serialized as a pipe-encoded string.
static String	encode(Type source, EncodingCharacters encodingChars) Encodes the given Type, using the given encoding characters.
String	getAckID(String message) For response messages, returns the value of MSA-2 (the message ID of the message sent by the sending system).
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.
String	getDefaultEncoding()
String	getEncoding(String message) Returns a String representing the encoding of the given message, if the encoding is recognized.
static PipeParser	getInstanceWithNoValidation() Convenience factory method which returns an instance that has a new DefaultHapiContext initialized with a NoValidation validation context.
String	getMessageStructure(String message) Deprecated. this method should not be public
String	getVersion(String message) Returns the version ID (MSH-12) from the given message, without fully parsing the message.
boolean	isLegacyMode() Deprecated. This will be removed in HAPI 3.0
void	parse(Message message, String string) Parses a particular message and returns the encoded structure
void	parse(Segment destination, String segment, EncodingCharacters encodingChars) Parses a segment string and populates the given Segment object.
void	parse(Segment destination, String segment, EncodingCharacters encodingChars, int theRepetition) Parses a segment string and populates the given Segment object.
Message	parse(String message) Parses a message string and returns the corresponding Message object.
void	parse(Type destinationField, String data, EncodingCharacters encodingCharacters) Fills a field with values from an unparsed string representing the field.
void	setLegacyMode(boolean legacyMode) Deprecated. This will be removed in HAPI 3.0
void	setValidationContext(ValidationContext context)
static String[]	split(String composite, String delim) Splits the given composite string into an array of components using the given delimiter.
static String	stripLeadingWhitespace(String in) Removes leading whitespace from the given string.

Methods inherited from class ca.uhn.hl7v2.parser.Parser

applySuperStructureName, assertVersionExists, encode, getFactory, getMessageStructureForEvent, getParserConfiguration, getValidationContext, instantiateMessage, instantiateMessageInASpecificPackage, makeControlMSH, parseForSpecificPackage, setParserConfiguration, supportsEncoding, validVersion

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

Field Detail

DEFAULT_LEGACY_MODE_PROPERTY

public static final String DEFAULT_LEGACY_MODE_PROPERTY

Deprecated. This will be removed in HAPI 3.0

System property key. If value is "true", legacy mode will default to true

See Also:

isLegacyMode(), Constant Field Values

Constructor Detail

PipeParser

public PipeParser()

PipeParser

public PipeParser(HapiContext context)

Parameters:

context - the context containing all configuration items to be used

PipeParser

public PipeParser(ModelClassFactory theFactory)

Creates a new PipeParser

Parameters:

theFactory - custom factory to use for model class lookup

Method Detail

setValidationContext

public void setValidationContext(ValidationContext context)

Overrides:

setValidationContext in class Parser

Parameters:

context - the set of validation rules to be applied to messages parsed or encoded by this parser (defaults to ValidationContextFactory.DefaultValidation)

getEncoding

public 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.

Specified by:

getEncoding in class Parser

Parameters:

message - message string

Returns:

string representing the encoding of the given message, i.e. "XML" or "ER7"

getDefaultEncoding

public String getDefaultEncoding()

Specified by:

getDefaultEncoding in class Parser

Returns:

the preferred encoding of this Parser

getMessageStructure

public String getMessageStructure(String message)
                           throws HL7Exception

Deprecated. this method should not be public

Parameters:

message - HL7 message

Returns:

message structure

Throws:

HL7Exception

doParse

protected Message doParse(String message,
                          String version)
                   throws HL7Exception

Parses a message string and returns the corresponding Message object. Unexpected segments added at the end of their group.

Specified by:

doParse in class Parser

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.

doParseForSpecificPackage

protected Message doParseForSpecificPackage(String message,
                                            String version,
                                            String packageName)
                                     throws HL7Exception

Attempt the parse a message using a specific model package

Specified by:

doParseForSpecificPackage in class Parser

Throws:

HL7Exception

parse

public void parse(Segment destination,
                  String segment,
                  EncodingCharacters encodingChars)
           throws HL7Exception

Parses a segment string and populates the given Segment object. Unexpected fields are added as Varies' at the end of the segment.

Specified by:

parse in class Parser

Parameters:

destination - segment to parse the segment string into

segment - encoded segment

encodingChars - encoding characters to be used

Throws:

HL7Exception - if the given string does not contain the given segment or if the string is not encoded properly

parse

public void parse(Segment destination,
                  String segment,
                  EncodingCharacters encodingChars,
                  int theRepetition)
           throws HL7Exception

Parses a segment string and populates the given Segment object. Unexpected fields are added as Varies' at the end of the segment.

Parameters:

destination - segment to parse the segment string into

segment - encoded segment

encodingChars - encoding characters to be used

theRepetition - the repetition number of this segment within its group

Throws:

HL7Exception - if the given string does not contain the given segment or if the string is not encoded properly

parse

public void parse(Type destinationField,
                  String data,
                  EncodingCharacters encodingCharacters)
           throws HL7Exception

Fills a field with values from an unparsed string representing the field.

Specified by:

parse in class Parser

Parameters:

destinationField - the field Type

data - the field string (including all components and subcomponents; not including field delimiters)

encodingCharacters - the encoding characters used in the message

Throws:

HL7Exception - If there is a problem encoding

split

public static String[] split(String composite,
                             String delim)

Splits the given composite string into an array of components using the given delimiter.

Parameters:

composite - encoded composite string

delim - delimiter to split upon

Returns:

split string

doEncode

public String doEncode(Segment structure,
                       EncodingCharacters encodingCharacters)
                throws HL7Exception

Encodes a particular segment and returns the encoded structure

Specified by:

doEncode in class Parser

Parameters:

structure - The structure to encode

encodingCharacters - The encoding characters

Returns:

The encoded segment

Throws:

HL7Exception - If there is a problem encoding

doEncode

public String doEncode(Type type,
                       EncodingCharacters encodingCharacters)
                throws HL7Exception

Encodes a particular type and returns the encoded structure

Specified by:

doEncode in class Parser

Parameters:

type - The type to encode

encodingCharacters - The encoding characters

Returns:

The encoded type

Throws:

HL7Exception - If there is a problem encoding

encode

public static String encode(Type source,
                            EncodingCharacters encodingChars)

Encodes the given Type, using the given encoding characters. It is assumed that the Type represents a complete field rather than a component.

Parameters:

source - type to be encoded

encodingChars - encoding characters to be used

Returns:

encoded type

doEncode

protected String doEncode(Message source,
                          String encoding)
                   throws HL7Exception

Formats a Message object into an HL7 message string using the given encoding.

Specified by:

doEncode in class Parser

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 String doEncode(Message source)
                   throws HL7Exception

Formats a Message object into an HL7 message string using this parser's default encoding ("VB").

Specified by:

doEncode in class Parser

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)

encode

public static String encode(Group source,
                            EncodingCharacters encodingChars)
                     throws HL7Exception

Returns given group serialized as a pipe-encoded string - this method is called by encode(Message source, String encoding).

Parameters:

source - group to be encoded

encodingChars - encoding characters to be used

Returns:

encoded group

Throws:

HL7Exception - if an error occurred while encoding

getInstanceWithNoValidation

public static PipeParser getInstanceWithNoValidation()

Convenience factory method which returns an instance that has a new DefaultHapiContext initialized with a NoValidation validation context.

Returns:

PipeParser with disabled validation

encode

public static String encode(Segment source,
                            EncodingCharacters encodingChars)

Returns given segment serialized as a pipe-encoded string.

Parameters:

source - segment to be encoded

encodingChars - encoding characters to be used

Returns:

encoded group

stripLeadingWhitespace

public static String stripLeadingWhitespace(String in)

Removes leading whitespace from the given string. This method was created to deal with frequent problems parsing messages that have been hand-written in windows. The intuitive way to delimit segments is to hit at the end of each segment, but this creates both a carriage return and a line feed, so to the parser, the first character of the next segment is the line feed.

Parameters:

in - input string

Returns:

string with leading whitespaces removed

getCriticalResponseData

public 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. The other fields in the returned MSH segment are empty.

Specified by:

getCriticalResponseData in class Parser

Parameters:

message - the message

Returns:

an MSH segment

Throws:

HL7Exception - if no MSH segment could be created

getAckID

public 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. Returns null if MSA-2 can not be found (e.g. if the message is not a response message).

Specified by:

getAckID in class Parser

Parameters:

message - the message

Returns:

the value of MSA-2

setLegacyMode

public void setLegacyMode(boolean legacyMode)

Deprecated. This will be removed in HAPI 3.0

Defaults to false

See Also:

isLegacyMode()

encode

public String encode(Message source)
              throws HL7Exception

Formats a Message object into an HL7 message string using this parser's default encoding.

Overrides:

encode in class Parser

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)

parse

public Message parse(String message)
              throws HL7Exception

Parses a message string and returns the corresponding Message object.

Overrides:

parse in class Parser

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.

isLegacyMode

public boolean isLegacyMode()

Deprecated. This will be removed in HAPI 3.0

Returns true if legacy mode is on.

Prior to release 1.0, when an unexpected segment was encountered in a message, HAPI would recurse to the deepest nesting in the last group it encountered after the current position in the message, and deposit the segment there. This could lead to unusual behaviour where all segments afterward would not be in an expected spot within the message.

This should normally be set to false, but any code written before the release of HAPI 1.0 which depended on this behaviour might need legacy mode to be set to true.

Defaults to false. Note that this method only overrides behaviour of the parse(java.lang.String) and encode(ca.uhn.hl7v2.model.Message) methods

getVersion

public 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.

Specified by:

getVersion in class Parser

Parameters:

message - the message

Returns:

the value of MSH-12

Throws:

HL7Exception - if the version field can not be found.

parse

public void parse(Message message,
                  String string)
           throws HL7Exception

Description copied from class: Parser

Parses a particular message and returns the encoded structure

Specified by:

parse in class Parser

Parameters:

message - The message to encode

string - The string to parse

Throws:

HL7Exception - If there is a problem encoding