ca.uhn.hl7v2.parser
Class FastParser

java.lang.Object
  extended by ca.uhn.hl7v2.parser.Parser
      extended by ca.uhn.hl7v2.parser.FastParser

public class FastParser
extends Parser

A Parser for the ER7 encoding, which is faster than PipeParser, but fussier and harder to use. It's harder to use in that you must tell it ahead of time which segments and fields to parse for each event, as well as where in a message structure to find each segment. It's fussier in that each segment you identify as to-be-parsed must always be present in the message (although it can be empty -- the minimum needed is the segment name and a carriage return). Note that an instance of configuration data (see StructRef below) takes on some state during parsing, so it can only be used to parse one message at a time. There is a synchronized block to ensure this, but if parallel parsing with the same configuration (e.g. parsing multiple messages of the same event at once) is needed, you may want to pool some FastParsers or use separate ones in separate threads.

Version:
$Revision: 1.3 $ updated on $Date: 2009/10/03 15:25:46 $ by $Author: jamesagnew $
Author:
Bryan Tripp

Nested Class Summary
static class FastParser.RootRef
          A convenience StructRef that points to a message root.
static class FastParser.StructRef
          A pointer to a distinct segment or group position in a message.
 
Constructor Summary
FastParser(java.util.Map theEventGuideMap)
           
FastParser(ModelClassFactory theFactory, java.util.Map theEventGuideMap)
           
 
Method Summary
protected  java.lang.String doEncode(Message source)
          Called by encode(Message) to perform implementation-specific encoding work.
protected  java.lang.String doEncode(Message source, java.lang.String encoding)
          Called by encode(Message, String) to perform implementation-specific encoding work.
 java.lang.String doEncode(Segment structure, EncodingCharacters encodingCharacters)
          Not supported, throws UnsupportedOperationException
 java.lang.String doEncode(Type type, EncodingCharacters encodingCharacters)
          Not supported, throws UnsupportedOperationException
protected  Message doParse(java.lang.String message, java.lang.String version)
          Called by parse() to perform implementation-specific parsing work.
 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).
 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.
 java.lang.String getDefaultEncoding()
           
 java.lang.String getEncoding(java.lang.String message)
          Returns a String representing the encoding of the given message, if the encoding is recognized.
 java.lang.String getVersion(java.lang.String message)
          Returns the version ID (MSH-12) from the given message, without fully parsing the message.
static java.util.Map loadEventGuideMap(java.net.URL theMapURL)
          Loads a parsing guide map (as required for FastParser instantiation).
 void parse(Message message, java.lang.String string)
          Not supported, throws UnsupportedOperationException
 void parse(Segment segment, java.lang.String string, EncodingCharacters encodingCharacters)
          Not supported, throws UnsupportedOperationException
 void parse(Type type, java.lang.String string, EncodingCharacters encodingCharacters)
          Not supported, throws UnsupportedOperationException
 boolean supportsEncoding(java.lang.String encoding)
          Returns true if and only if the given encoding is supported by this Parser.
 
Methods inherited from class ca.uhn.hl7v2.parser.Parser
encode, encode, getFactory, getMessageStructureForEvent, getMessageStructures, getValidationContext, getValidVersions, instantiateMessage, makeControlMSH, parse, setValidationContext, validVersion
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FastParser

public FastParser(java.util.Map theEventGuideMap)
Parameters:
theEventGuideMap - a map with keys in the form "type^event" (like MSH-9 components 1 and 2). Values are corresponding parsing guides for those events. A parsing guide is a group of StructRef that identify which segments to parse, the relationships between them, and where to find them in a message hierarchy. The value in the map is the RootRef of the message root. It must return the StructRef for the MSH segment from getSuccessor("MSH"). References to other segments can be included as needed.

FastParser

public FastParser(ModelClassFactory theFactory,
                  java.util.Map theEventGuideMap)
Parameters:
theFactory - custom factory to use for model class lookup
theEventGuideMap - a map with keys in the form "type^event" (like MSH-9 components 1 and 2). Values are corresponding parsing guides for those events. A parsing guide is a group of StructRef that identify which segments to parse, the relationships between them, and where to find them in a message hierarchy. The value in the map is the RootRef of the message root. It must return the StructRef for the MSH segment from getSuccessor("MSH"). References to other segments can be included as needed.
Method Detail

loadEventGuideMap

public static java.util.Map loadEventGuideMap(java.net.URL theMapURL)
                                       throws HL7Exception
Loads a parsing guide map (as required for FastParser instantiation). The URL should point to a file with one or more guides in sections delimited by blank lines. Within a section, the first line must contain an event name of the for "type^event". Subsequent lines define the parsed parts of messages with that event. Each line begins with either a segment name or "{" (indicating group start) or "}" (indicating group end). Group start lines then have whitespace and a Terser path to the group (relative to the closest ancestor group listed in the parsin guide). Segment lines then have whitespace and a relative Terser path to the segment, followed by a colon and a comma-delimited list of field numbers, which indicates which fields for that segment are to be parsed. Within Terser paths, repetition numbers must be replaced with asterisks. An example follows: ORU^R01 MSH MSH:9,12 { ORU_R01_PIDNTEPV1ORCOBRNTEOBXNTE(*) { ORU_R01_PIDNTEPV1 PID PID:3-5 } { ORU_R01_ORCOBRNTEOBXNTE(*) { ORU_R01_OBXNTE(*) OBX OBX:2,5 } } } ADT^A01 MSH MSH:9,12 PID PID:3 PV1 PV1:7-9

Parameters:
theMapURL - an URL to a file of the form desribed above
Returns:
the corresponding Map
Throws:
HL7Exception

getEncoding

public java.lang.String getEncoding(java.lang.String message)
Description copied from class: Parser
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
See Also:
Parser.getEncoding(java.lang.String)

supportsEncoding

public boolean supportsEncoding(java.lang.String encoding)
Description copied from class: Parser
Returns true if and only if the given encoding is supported by this Parser.

Specified by:
supportsEncoding in class Parser
See Also:
Parser.supportsEncoding(java.lang.String)

getDefaultEncoding

public java.lang.String getDefaultEncoding()
Specified by:
getDefaultEncoding in class Parser
Returns:
the preferred encoding of this Parser

doParse

protected Message doParse(java.lang.String message,
                          java.lang.String version)
                   throws HL7Exception,
                          EncodingNotSupportedException
Description copied from class: Parser
Called by parse() to perform implementation-specific parsing work.

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.
See Also:
Parser.doParse(java.lang.String, java.lang.String)

doEncode

protected java.lang.String doEncode(Message source,
                                    java.lang.String encoding)
                             throws HL7Exception,
                                    EncodingNotSupportedException
Description copied from class: Parser
Called by encode(Message, String) to perform implementation-specific encoding work.

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.
See Also:
Parser.encode(ca.uhn.hl7v2.model.Message, java.lang.String)

doEncode

protected java.lang.String doEncode(Message source)
                             throws HL7Exception
Description copied from class: Parser
Called by encode(Message) to perform implementation-specific encoding work.

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)
EncodingNotSupportedException - if the requested encoding is not supported by this parser.
See Also:
Parser.encode(ca.uhn.hl7v2.model.Message)

getCriticalResponseData

public Segment getCriticalResponseData(java.lang.String message)
                                throws HL7Exception
Description copied from class: Parser

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.

Specified by:
getCriticalResponseData in class Parser
Returns:
an MSH segment
Throws:
HL7Exception
See Also:
Parser.getCriticalResponseData(java.lang.String)

getAckID

public java.lang.String getAckID(java.lang.String message)
Description copied from class: Parser
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).

Specified by:
getAckID in class Parser
See Also:
Parser.getAckID(java.lang.String)

getVersion

public java.lang.String getVersion(java.lang.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
Throws:
HL7Exception - if the version field can not be found.
See Also:
Parser.getVersion(java.lang.String)

doEncode

public java.lang.String doEncode(Segment structure,
                                 EncodingCharacters encodingCharacters)
                          throws HL7Exception
Not supported, throws UnsupportedOperationException

Specified by:
doEncode in class Parser
Parameters:
structure - The structure to encode
encodingCharacters - The encoding characters
Returns:
The encoded segment
Throws:
java.lang.UnsupportedOperationException
HL7Exception - If there is a problem encoding

doEncode

public java.lang.String doEncode(Type type,
                                 EncodingCharacters encodingCharacters)
                          throws HL7Exception
Not supported, throws UnsupportedOperationException

Specified by:
doEncode in class Parser
Parameters:
type - The type to encode
encodingCharacters - The encoding characters
Returns:
The encoded type
Throws:
java.lang.UnsupportedOperationException
HL7Exception - If there is a problem encoding

parse

public void parse(Type type,
                  java.lang.String string,
                  EncodingCharacters encodingCharacters)
           throws HL7Exception
Not supported, throws UnsupportedOperationException

Specified by:
parse in class Parser
Parameters:
type - The type to encode
string - The string to parse
encodingCharacters - The encoding characters
Throws:
java.lang.UnsupportedOperationException
HL7Exception - If there is a problem encoding

parse

public void parse(Segment segment,
                  java.lang.String string,
                  EncodingCharacters encodingCharacters)
           throws HL7Exception
Not supported, throws UnsupportedOperationException

Specified by:
parse in class Parser
Parameters:
segment - The segment to encode
string - The string to parse
encodingCharacters - The encoding characters
Throws:
java.lang.UnsupportedOperationException
HL7Exception - If there is a problem encoding

parse

public void parse(Message message,
                  java.lang.String string)
           throws HL7Exception
Not supported, throws UnsupportedOperationException

Specified by:
parse in class Parser
Parameters:
message - The message to encode
string - The string to parse
Throws:
java.lang.UnsupportedOperationException
HL7Exception - If there is a problem encoding


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