ca.uhn.hl7v2.model

Interface Message

All Superinterfaces:

Group, Serializable, Structure, Visitable

All Known Implementing Classes:

AbstractMessage, AbstractSuperMessage, GenericMessage, GenericMessage.UnknownVersion, GenericMessage.V21, GenericMessage.V22, GenericMessage.V23, GenericMessage.V231, GenericMessage.V24, GenericMessage.V25, GenericMessage.V251, GenericMessage.V26, GenericMessage.V27, GenericMessage.V271, GenericMessage.V28, GenericMessage.V281

public interface Message
extends Group

Represents a complete HL7 message including all structures, segments, and fields.

Note this it is not recommended to implement this interface directly, as it is subject to change. Instead, extend abstract implementations for your model classes, such as AbstractMessage and AbstractGroup

Author:

Bryan Tripp (bryan_tripp@sourceforge.net)

Method Summary

Modifier and Type	Method and Description
String	encode() Encodes this message using the parser returned by getParser()
Message	generateACK() Generates and returns an ACK message which would be used to acknowledge this message successfully, with an MSA-1 code of "AA".
Message	generateACK(AcknowledgmentCode theAcknowlegementCode, HL7Exception theException) Generates and returns an ACK message which would be used to acknowledge this message successfully.
Message	generateACK(String theAcknowldegementCode, HL7Exception theException) Deprecated. use generateACK(AcknowledgmentCode, HL7Exception)
String	getEncodingCharactersValue() Convenience method which retrieves the encoding characters value from the second field of the first segment.
Character	getFieldSeparatorValue() Convenience method which retrieves the field separator value from the first field of the first segment.
Parser	getParser() Returns the parser to be used when parse/encode methods are called on this Message, as well as its children.
String	getVersion() Returns the version number of the HL7 version in which this message structure is defined (e.g.
void	parse(String string) Parses the string into this message using the parser returned by getParser()
String	printStructure() Prints a summary of the contents and structure of this message.
void	setParser(Parser parser) Sets the parser to be used when parse/encode methods are called on this Message, as well as its children.

Methods inherited from interface ca.uhn.hl7v2.model.Group

addNonstandardSegment, addNonstandardSegment, get, get, getAll, getClass, getNames, isChoiceElement, isGroup, isRepeating, isRequired

Methods inherited from interface ca.uhn.hl7v2.model.Structure

getMessage, getName, getParent

Methods inherited from interface ca.uhn.hl7v2.model.Visitable

accept, isEmpty, provideLocation

Method Detail

getVersion

String getVersion()

Returns the version number of the HL7 version in which this message structure is defined (e.g. "2.4")

Returns:

version number of the HL7 version

getFieldSeparatorValue

Character getFieldSeparatorValue()
                          throws HL7Exception

Convenience method which retrieves the field separator value from the first field of the first segment. Typically, the first segment is MSH, so this method will retrieve the value of MSH-1.

Returns:

The field separator

Throws:

HL7Exception - If an error occurs

Since:

1.0

getEncodingCharactersValue

String getEncodingCharactersValue()
                           throws HL7Exception

Convenience method which retrieves the encoding characters value from the second field of the first segment. Typically, the first segment is MSH, so this method will retrieve the value of MSH-2.

Returns:

The encoding characters

Throws:

HL7Exception - If an error occurs

Since:

1.0

setParser

void setParser(Parser parser)

Sets the parser to be used when parse/encode methods are called on this Message, as well as its children. It is recommended that if these methods are going to be called, a parser be supplied with the validation context wanted. Where possible, the parser should be reused for best performance, unless thread safety is an issue. Note that not all parsers can be used. As of version 1.0, only PipeParser supports this functionality

Parameters:

parser - the parser to be used when parse/encode methods are called on this Message

getParser

Parser getParser()

Returns the parser to be used when parse/encode methods are called on this Message, as well as its children. The default value is a new PipeParser.

Returns:

the parser to be used when parse/encode methods are called on this Message

parse

void parse(String string)
    throws HL7Exception

Parses the string into this message using the parser returned by getParser()

Parameters:

string - the message to be parsed

Throws:

HL7Exception - if errors occurred during parsing

encode

String encode()
       throws HL7Exception

Encodes this message using the parser returned by getParser()

Returns:

the string-encoded message

Throws:

HL7Exception - if error occurred during encoding

generateACK

Message generateACK()
             throws HL7Exception,
                    IOException

Generates and returns an ACK message which would be used to acknowledge this message successfully, with an MSA-1 code of "AA". The ACK generated will be of the same version as the value of MSH-12 in this message (as opposed to the version of the message class instance, if they are different)

Note that this method will fail if it is not possible to generate an ACK for any reason, such as

• Message version is invalid
• First segment is not an MSH

Returns:

the acknowledgment message

Throws:

HL7Exception - If the message can not be constructed

IOException - If a failure occurs in generating a control ID for the message

generateACK

Message generateACK(String theAcknowldegementCode,
                    HL7Exception theException)
             throws HL7Exception,
                    IOException

Deprecated. use generateACK(AcknowledgmentCode, HL7Exception)

Generates and returns an ACK message which would be used to acknowledge this message successfully. The ACK generated will be of the same version as the value of MSH-12 in this message (as opposed to the version of the message class instance, if they are different)

Note that this method will fail if it is not possible to generate an ACK for any reason, such as

• Message version is invalid
• First segment is not an MSH

Parameters:

theAcknowldegementCode - The acknowledement code (MSA-1) to supply. If null, defaults to "AA". To generate a typical NAK, use "AE"

theException - The exceptions used to populate the ERR segment (if any)

Throws:

HL7Exception - If the message can not be constructed

IOException - If a failure occurs in generating a control ID for the message

generateACK

Message generateACK(AcknowledgmentCode theAcknowlegementCode,
                    HL7Exception theException)
             throws HL7Exception,
                    IOException

Generates and returns an ACK message which would be used to acknowledge this message successfully. The ACK generated will be of the same version as the value of MSH-12 in this message (as opposed to the version of the message class instance, if they are different)

Note that this method will fail if it is not possible to generate an ACK for any reason, such as

• Message version is invalid
• First segment is not an MSH

Parameters:

theAcknowlegementCode - If null, defaults to AcknowledgmentCode.AA. To generate a typical NAK, use AcknowledgmentCode.AE

theException - The exceptions used to populate the ERR segment (if any)

Returns:

the acknoeldgement message

Throws:

HL7Exception - If the message can not be constructed

IOException - If a failure occurs in generating a control ID for the message

printStructure

String printStructure()
               throws HL7Exception

Prints a summary of the contents and structure of this message. This is useful for debugging purposes, if you want to figure out where in the structure of a message a given segment has been placed.

For instance, the following message (containing a few quirks for demonstration purposes):

MSH|^~\\&|^QueryServices||||20021011161756.297-0500||ADT^A01|1|D|2.4\r
 EVN|R01
 EVN|R02
 PID|1
 IN1|1
 IN1|2
 PID|2

...produces the following output:

ADT_A01 (start)
    MSH - MSH|^~\&|^QueryServices||||20021011161756.297-0500||ADT^A01|1|D|2.4
    EVN - EVN|R01
    [ { EVN2 } ] (non-standard) - EVN|R02
    PID - PID|1
    [ PD1 ] - Not populated
    [ { ROL } ] - Not populated
    [ { NK1 } ] - Not populated
    PV1 - Not populated
    [ PV2 ] - Not populated
    [ { ROL2 } ] - Not populated
    [ { DB1 } ] - Not populated
    [ { OBX } ] - Not populated
    [ { AL1 } ] - Not populated
    [ { DG1 } ] - Not populated
    [ DRG ] - Not populated
    PROCEDURE (start)
    [{
       PR1 - Not populated
       [ { ROL } ] - Not populated
    }]
    PROCEDURE (end)
    [ { GT1 } ] - Not populated
    INSURANCE (start)
    [{
       IN1 - IN1|1
       [ IN2 ] - Not populated
       [ { IN3 } ] - Not populated
       [ { ROL } ] - Not populated
    }]
    [{
       IN1 - IN1|2
       [ { PID } ] (non-standard) - PID|2
       [ IN2 ] - Not populated
       [ { IN3 } ] - Not populated
       [ { ROL } ] - Not populated
    }]
    INSURANCE (end)
    [ ACC ] - Not populated
    [ UB1 ] - Not populated
    [ UB2 ] - Not populated
    [ PDA ] - Not populated
 ADT_A01 (end)
 

Returns:

A summary of the structure

Throws:

HL7Exception - If any problems occur encoding the structure