ca.uhn.hl7v2.parser

Class XMLParser

java.lang.Object

ca.uhn.hl7v2.HapiContextSupport

ca.uhn.hl7v2.parser.Parser

ca.uhn.hl7v2.parser.XMLParser

Direct Known Subclasses:

DefaultXMLParser

public abstract class XMLParser
extends Parser

Parses and encodes HL7 messages in XML form, according to HL7's normative XML encoding specification. This is an abstract class that handles datatype and segment parsing/encoding, but not the parsing/encoding of entire messages. To use the XML parser, you should create a subclass for a certain message structure. This subclass must be able to identify the Segment objects that correspond to various Segment nodes in an XML document, and call the methods parse(Segment segment, ElementNode segmentNode) and encode(Segment segment, ElementNode segmentNode) as appropriate. XMLParser uses the Xerces parser, which must be installed in your classpath.

Author:

Bryan Tripp, Shawn Bellina

See Also:

for configuration options which may affect parser encoding and decoding behaviour

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	NS

Constructor Summary

Constructors

Constructor and Description
XMLParser() Constructor
XMLParser(HapiContext context)
XMLParser(ModelClassFactory theFactory) Constructor

Method Summary

Modifier and Type	Method and Description
protected void	assertNamespaceURI(String ns)
protected String	doEncode(Message source) Formats a Message object into an HL7 message string using this parser's default encoding (XML encoding).
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) Throws unsupported operation exception
String	doEncode(Type type, EncodingCharacters encodingCharacters) Throws unsupported operation exception
protected Message	doParse(String message, String version) Parses a message string and returns the corresponding Message object.
protected Message	doParseForSpecificPackage(String theMessage, String theVersion, String thePackageName) Throws unsupported operation exception
boolean	encode(Segment segmentObject, Element segmentElement) Populates the given Element with data from the given Segment, by inserting Elements corresponding to the Segment's fields, their components, etc.
abstract Document	encodeDocument(Message source) Creates an XML Document that corresponds to the given Message object.
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.
String[]	getKeepAsOriginalNodes() Deprecated. Use ParserConfiguration.getXmlDisableWhitespaceTrimmingOnNodeNames() instead
String	getTextEncoding() Returns the text encoding to be used in generating new messages.
String	getVersion(String message) Returns the version ID (MSH-12) from the given message, without fully parsing the message.
protected boolean	keepAsOriginal(Node node) Checks if Node content should be kept as original (ie.: whitespaces won't be removed)
void	parse(Segment segmentObject, Element segmentElement) Populates the given Segment object with data from the given XML Element.
void	parse(Segment segment, String string, EncodingCharacters encodingCharacters) Throws unsupported operation exception
void	parse(Type datatypeObject, Element datatypeElement) Populates the given Type object with data from the given XML Element.
void	parse(Type type, String string, EncodingCharacters encodingCharacters) Throws unsupported operation exception
abstract Message	parseDocument(Document xmlMessage, String version) Creates and populates a Message object from an XML Document that contains an XML-encoded HL7 message.
protected static String	parseLeaf(String message, String tagName, int startAt) Attempts to retrieve the value of a leaf tag without using DOM or SAX.
protected Document	parseStringIntoDocument(String message) Parses a string containing an XML document into a Document object.
protected String	removeWhitespace(String s) Removes all unnecessary whitespace from the given String (intended to be used with Primitive values).
void	setKeepAsOriginalNodes(String[] keepAsOriginalNodes) Deprecated. Use ParserConfiguration.setXmlDisableWhitespaceTrimmingOnNodeNames(Set) instead. That method works exactly the same as this one but has been renamed for a more clear meaning.
void	setTextEncoding(String textEncoding) Sets the text encoding to be used in generating new messages.

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

applySuperStructureName, assertVersionExists, encode, encode, getFactory, getMessageStructureForEvent, getParserConfiguration, getValidationContext, instantiateMessage, instantiateMessageInASpecificPackage, makeControlMSH, parse, parse, parseForSpecificPackage, setParserConfiguration, setValidationContext, 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

NS

protected static final String NS

See Also:

Constant Field Values

Constructor Detail

XMLParser

public XMLParser()

Constructor

XMLParser

public XMLParser(HapiContext context)

Parameters:

context - the HAPI context

XMLParser

public XMLParser(ModelClassFactory theFactory)

Constructor

Parameters:

theFactory - custom factory to use for model class lookup

Method Detail

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. Returns null if the encoding is not recognized.

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

setKeepAsOriginalNodes

@Deprecated
public void setKeepAsOriginalNodes(String[] keepAsOriginalNodes)

Deprecated. Use ParserConfiguration.setXmlDisableWhitespaceTrimmingOnNodeNames(Set) instead. That method works exactly the same as this one but has been renamed for a more clear meaning.

Sets the keepAsOriginalNodes The nodes whose names match the keepAsOriginalNodes will be kept as original, meaning that no white space treaming will occur on them

Parameters:

keepAsOriginalNodes - of the nodes to be kept as original

getKeepAsOriginalNodes

@Deprecated
public String[] getKeepAsOriginalNodes()

Deprecated. Use ParserConfiguration.getXmlDisableWhitespaceTrimmingOnNodeNames() instead

Sets the keepAsOriginalNodes

parseDocument

public abstract Message parseDocument(Document xmlMessage,
                                      String version)
                               throws HL7Exception

Creates and populates a Message object from an XML Document that contains an XML-encoded HL7 message.

The easiest way to implement this method for a particular message structure is as follows:

1. Create an instance of the Message type you are going to handle with your subclass of XMLParser
2. Go through the given Document and find the Elements that represent the top level of each message segment.
3. For each of these segments, call parse(Segment segmentObject, Element segmentElement), providing the appropriate Segment from your Message object, and the corresponding Element.

At the end of this process, your Message object should be populated with data from the XML Document.

Parameters:

xmlMessage - DOM message object to be parsed

version - HL7 version

Throws:

HL7Exception - if the message is not correctly formatted.

EncodingNotSupportedException - if the message encoded is not supported by this parser.

doParse

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

Parses a message string and returns the corresponding Message object. This method checks that the given message string is XML encoded, creates an XML Document object (using Xerces) from the given String, and calls the abstract method parse(Document XMLMessage)

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.

parseStringIntoDocument

protected Document parseStringIntoDocument(String message)
                                    throws HL7Exception

Parses a string containing an XML document into a Document object. Note that this method is synchronized currently, as the XML parser is not thread safe

Throws:

HL7Exception

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 (XML encoding). This method calls the abstract method encodeDocument(...) in order to obtain XML Document object representation of the Message, then serializes it to a String.

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)

encodeDocument

public abstract Document encodeDocument(Message source)
                                 throws HL7Exception

Creates an XML Document that corresponds to the given Message object.

If you are implementing this method, you should create an XML Document, and insert XML Elements into it that correspond to the groups and segments that belong to the message type that your subclass of XMLParser supports. Then, for each segment in the message, call the method encode(Segment segmentObject, Element segmentElement) using the Element for that segment and the corresponding Segment object from the given Message.

Parameters:

source - message

Returns:

the DOM document object of the encoded message

Throws:

HL7Exception

assertNamespaceURI

protected void assertNamespaceURI(String ns)
                           throws HL7Exception

Throws:

HL7Exception

parse

public void parse(Segment segmentObject,
                  Element segmentElement)
           throws HL7Exception

Populates the given Segment object with data from the given XML Element.

Parameters:

segmentObject - the segment to parse into

segmentElement - the DOM element to be parsed

Throws:

HL7Exception - if the XML Element does not have the correct name and structure for the given Segment, or if there is an error while setting individual field values.

encode

public boolean encode(Segment segmentObject,
                      Element segmentElement)
               throws HL7Exception

Populates the given Element with data from the given Segment, by inserting Elements corresponding to the Segment's fields, their components, etc. Returns true if there is at least one data value in the segment.

Parameters:

segmentObject - the segment to be encoded

segmentElement - the DOM element to encode into

Returns:

true if there is at least one data value in the segment

Throws:

HL7Exception - if an erro occurred while encoding

parse

public void parse(Type datatypeObject,
                  Element datatypeElement)
           throws HL7Exception

Populates the given Type object with data from the given XML Element.

Parameters:

datatypeObject - the type to parse into

datatypeElement - the DOM element to be parsed

Throws:

DataTypeException - if the data did not match the expected type rules

HL7Exception

keepAsOriginal

protected boolean keepAsOriginal(Node node)

Checks if Node content should be kept as original (ie.: whitespaces won't be removed)

Parameters:

node - The target Node

Returns:

boolean true if whitespaces should not be removed from node content, false otherwise

removeWhitespace

protected String removeWhitespace(String s)

Removes all unnecessary whitespace from the given String (intended to be used with Primitive values). This includes leading and trailing whitespace, and repeated space characters. Carriage returns, line feeds, and tabs are replaced with spaces.

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.

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. 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). Trims whitespace from around the MSA-2 field.

Specified by:

getAckID in class Parser

Parameters:

message - the message

Returns:

the value of MSA-2

getVersion

public String getVersion(String message)
                  throws HL7Exception

Description copied from class: Parser

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.

parseLeaf

protected static String parseLeaf(String message,
                                  String tagName,
                                  int startAt)
                           throws HL7Exception

Attempts to retrieve the value of a leaf tag without using DOM or SAX. This method searches the given message string for the given tag name, and returns everything after the given tag and before the start of the next tag. Whitespace is stripped. This is intended only for lead nodes, as the value is considered to end at the start of the next tag, regardless of whether it is the matching end tag or some other nested tag.

Parameters:

message - a string message in XML form

tagName - the name of the XML tag, e.g. "MSA.2"

startAt - the character location at which to start searching

Throws:

HL7Exception - if the tag can not be found

doEncode

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

Throws unsupported operation exception

Specified by:

doEncode in class Parser

Parameters:

structure - The structure to encode

encodingCharacters - The encoding characters

Returns:

The encoded segment

Throws:

UnsupportedOperationException

HL7Exception - If there is a problem encoding

doParseForSpecificPackage

protected Message doParseForSpecificPackage(String theMessage,
                                            String theVersion,
                                            String thePackageName)
                                     throws HL7Exception

Throws unsupported operation exception

Specified by:

doParseForSpecificPackage in class Parser

Throws:

UnsupportedOperationException

HL7Exception

doEncode

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

Throws unsupported operation exception

Specified by:

doEncode in class Parser

Parameters:

type - The type to encode

encodingCharacters - The encoding characters

Returns:

The encoded type

Throws:

UnsupportedOperationException

HL7Exception - If there is a problem encoding

parse

public void parse(Type type,
                  String string,
                  EncodingCharacters encodingCharacters)
           throws HL7Exception

Throws unsupported operation exception

Specified by:

parse in class Parser

Parameters:

type - The type to encode

string - The string to parse

encodingCharacters - The encoding characters

Throws:

UnsupportedOperationException

HL7Exception - If there is a problem encoding

parse

public void parse(Segment segment,
                  String string,
                  EncodingCharacters encodingCharacters)
           throws HL7Exception

Throws unsupported operation exception

Specified by:

parse in class Parser

Parameters:

segment - The segment to encode

string - The string to parse

encodingCharacters - The encoding characters

Throws:

UnsupportedOperationException

HL7Exception - If there is a problem encoding

getTextEncoding

public String getTextEncoding()

Returns the text encoding to be used in generating new messages. Note that this affects encoding to string only, not parsing.

Returns:

text encoding

setTextEncoding

public void setTextEncoding(String textEncoding)

Sets the text encoding to be used in generating new messages. Note that this affects encoding to string only, not parsing.

Parameters:

textEncoding - The encoding. Default is the platform default.