ca.uhn.hl7v2.protocol
Interface Processor

All Known Implementing Classes:
ProcessorImpl

public interface Processor

Encapsulates both the client and server roles of the HL7-defined "original mode" and "enhanced mode" processing rules. See HL7 v2.5 chapter 2 for specifications.

Version:
$Revision: 1.1 $ updated on $Date: 2007/02/19 02:24:38 $ by $Author: jamesagnew $
Author:
Bryan Tripp

Field Summary
static java.lang.String AA
          Original mode: Application Accept - Enhanced mode: Application acknowledgment: Accept
static java.lang.String AE
          Original mode: Application Error - Enhanced mode: Application acknowledgment: Error
static java.lang.String AL
          Always send acknowledgement (in MSH-15 and 16)
static java.lang.String AR
          Original mode: Application Reject - Enhanced mode: Application acknowledgment: Reject
static java.lang.String CA
          Enhanced mode: Accept acknowledgment: Commit Accept
static java.lang.String CE
          Enhanced mode: Accept acknow ledgment: Commit Error
static java.lang.String CR
          Enhanced mode: Accept acknowledgment: Commit Reject
static java.lang.String ER
          Send acknowledgement only on error / reject (in MSH-15 and 16)
static java.lang.String NE
          Never send acknowledgement (in MSH-15 and 16)
static java.lang.String SU
          Send acknowledgement only on successful receipt (in MSH-15 and 16)
 
Method Summary
 void cycle(boolean expectingAck)
          Performs a single iteration of the receiving-side of the HL7 original mode or enhanced mode processing rules (see HL7 Standard v2.5 Chapter 2; the choice of rules is determined by message values).
 ProcessorContext getContext()
           
 boolean isAvailable(java.lang.String theAckId)
           
 Transportable receive(java.lang.String theAckId, long theTimeoutMillis)
          Gets the message with the given acknowledgement ID from the incoming message list.
 void reserve(java.lang.String theAckId, long thePeriodMillis)
          Indicates that the calling thread expects a message with a certain ack ID.
 void send(Transportable theMessage, int maxRetries, long retryIntervalMillis)
          Sends a message to a remote system via an underlying TransportLayer.
 

Field Detail

AL

static final java.lang.String AL
Always send acknowledgement (in MSH-15 and 16)

See Also:
Constant Field Values

NE

static final java.lang.String NE
Never send acknowledgement (in MSH-15 and 16)

See Also:
Constant Field Values

ER

static final java.lang.String ER
Send acknowledgement only on error / reject (in MSH-15 and 16)

See Also:
Constant Field Values

SU

static final java.lang.String SU
Send acknowledgement only on successful receipt (in MSH-15 and 16)

See Also:
Constant Field Values

AA

static final java.lang.String AA
Original mode: Application Accept - Enhanced mode: Application acknowledgment: Accept

See Also:
Constant Field Values

AE

static final java.lang.String AE
Original mode: Application Error - Enhanced mode: Application acknowledgment: Error

See Also:
Constant Field Values

AR

static final java.lang.String AR
Original mode: Application Reject - Enhanced mode: Application acknowledgment: Reject

See Also:
Constant Field Values

CA

static final java.lang.String CA
Enhanced mode: Accept acknowledgment: Commit Accept

See Also:
Constant Field Values

CE

static final java.lang.String CE
Enhanced mode: Accept acknow ledgment: Commit Error

See Also:
Constant Field Values

CR

static final java.lang.String CR
Enhanced mode: Accept acknowledgment: Commit Reject

See Also:
Constant Field Values
Method Detail

send

void send(Transportable theMessage,
          int maxRetries,
          long retryIntervalMillis)
          throws HL7Exception
Sends a message to a remote system via an underlying TransportLayer. If the message specifies that an accept ACK is required (under enhanced mode processing rules) then this method may retry if transmission does not appear to be successful. The call to this method blocks while this is happening. Retries are attempted if a CR message is received, or if no message is received in the specified time frame. If a CE is received, an exception is thrown. If a CA is received, the call returns quietly. If no accept ack is required, this method returns immediately after attempting to send a message, throwing an exception only if there is an immediate problem (eg the server can't be contacted). If an accept ack is required only on error, the method waits for maxRetries * retryItervalMillis for an error to be returned, and assumes that there is no error if none appears in that time. The message is not actually resent while waiting for an error ACK.

Parameters:
theMessage - the message to send
maxRetries - note that this should be a small value if you demand an accept ack only on error
retryIntervalMillis - note that this should be a small value if you demand an accept ack only on error
Throws:
TransportException - if there is an immediate problem trying to send the message.
HL7Exception

reserve

void reserve(java.lang.String theAckId,
             long thePeriodMillis)
Indicates that the calling thread expects a message with a certain ack ID. If this message arrives within the specified period of time, it will be held in an inbound list instead of being passed on to an Application. If a message is in this list it isAvailable() and can be had via receive()

Parameters:
theAckId - the acknowledgement ID of the message
thePeriodMillis - time span during which the message should be kept if received

cycle

void cycle(boolean expectingAck)
           throws HL7Exception

Performs a single iteration of the receiving-side of the HL7 original mode or enhanced mode processing rules (see HL7 Standard v2.5 Chapter 2; the choice of rules is determined by message values). Steps in the process are as follows:

1. TransportLayer.receive() is called to get the next message
2. Validation is performed and the message is stored locally.
2. If the message requires an accept ACK, then an accept, reject, or error message is returned as appropriate
3. If the message is an accept ack, it is added to a local list that can be accessed by the send() method
4. If the message has been reserved, it is added to the available message list.
5. Otherwise it is sent to an Application.

Parameters:
expectingAck - is passed to TransportLayer.receive(), and may determine where the message is read from (eg different sockets may be used for commit-level ACKs). Note that this call blocks until a message is ready at the specified location, so to run the Processor continuously, separate threads are needed to call cycle() with true and false args.
Throws:
HL7Exception

isAvailable

boolean isAvailable(java.lang.String theAckId)
Parameters:
theAckId - the acknowledgement ID of an expected message
Returns:
true if the message has come in and has been saved in the inbound message list

receive

Transportable receive(java.lang.String theAckId,
                      long theTimeoutMillis)
                      throws HL7Exception
Gets the message with the given acknowledgement ID from the incoming message list. This method blocks until the message appears on the list. If you don't want to block, call isAvailable() to see if it is there. Note also that the message has no way of arriving on the list during this call unless the Processor is running as a thread, or unless some other thread is calling cycle().

Parameters:
theAckId -
theTimeoutMillis - milliseconds until the call times out and returns null if the desired message is not available.
Returns:
the incoming message with the given ack ID, or null if the call times out.
Throws:
HL7Exception

getContext

ProcessorContext getContext()
Returns:
the operational context of this protocol instance


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