Coverage Report

Coverage Report - ca.uhn.hl7v2.protocol.Processor

Classes in this File

 /*
  * Created on 16-Apr-2004
  */
 package ca.uhn.hl7v2.protocol;
 
 import ca.uhn.hl7v2.HL7Exception;
 
 /**
  * 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.    
  *  
  * @author <a href="mailto:bryan.tripp@uhn.on.ca">Bryan Tripp</a>
  * @version $Revision: 1.1 $ updated on $Date: 2007-02-19 02:24:38 $ by $Author: jamesagnew $
  */
 public interface Processor {
     
     /**
      * Always send acknowledgement (in MSH-15 and 16)
      */
     public static final String AL = "AL";
     
     /**
      * Never send acknowledgement (in MSH-15 and 16)
      */
     public static final String NE = "NE";
 
     /**
      * Send acknowledgement only on error / reject (in MSH-15 and 16)
      */
     public static final String ER = "ER";
     
     /**
      * Send acknowledgement only on successful receipt (in MSH-15 and 16)
      */
     public static final String SU = "SU";
         
     
     /**
      * Original mode: Application Accept - Enhanced mode: Application acknowledgment: Accept
      */
     public static final String AA = "AA"; 
     
     /**
      * Original mode: Application Error - Enhanced mode: Application acknowledgment: Error 
      */
     public static final String AE = "AE"; 
     /**
      * Original mode: Application Reject - Enhanced mode: Application acknowledgment: Reject
      */
     public static final String AR = "AR";
     
     /**
      * Enhanced mode: Accept acknowledgment: Commit Accept
      */
     public static final String CA = "CA"; 
     
     /**
      * Enhanced mode: Accept acknow ledgment: Commit Error
      */
     public static final String CE = "CE";
     
     /**
      * Enhanced mode: Accept acknowledgment: Commit Reject
      */
     public static final String CR = "CR";
     
     
     /**
      * Sends a message to a remote system via an underlying 
      * <code>TransportLayer</code>.  
      * 
      * 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. 
      * 
      * @param theMessage the message to send 
      * @param maxRetries note that this should be a small value if you demand an accept ack only
      *      on error
      * @param 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.  
      */
     public void send(Transportable theMessage, int maxRetries, long retryIntervalMillis) throws HL7Exception;
     
     /**
      * 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 
      * <code>Application</code>.  If a message is in this list it <code>isAvailable()</code>
      * and can be had via <code>receive()</code>
      * 
      * @param theAckId the acknowledgement ID of the message 
      * @param thePeriodMillis time span during which the message should be kept if received
      */
     public void reserve(String theAckId, long thePeriodMillis);
     
     /**
      * <p>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: </p>
      * 
      * 1. TransportLayer.receive() is called to get the next message <br> 
      * 2. Validation is performed and the message is stored locally. <br>
      * 2. If the message requires an accept ACK, then an accept, reject, 
      *   or error message is returned as appropriate  <br>
      * 3. If the message is an accept ack, it is added to a local list that 
      * can be accessed by the send() method <br>
      * 4. If the message has been reserved, it is added to the available message
      * list.  <br>
      * 5. Otherwise it is sent to an Application.   
      * 
      * @param 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.   
      */
     public void cycle(boolean expectingAck) throws HL7Exception; 
         
     /**
      * @param theAckId the acknowledgement ID of an expected message 
      * @return true if the message has come in and has been saved in the 
      *      inbound message list 
      */
     public boolean isAvailable(String theAckId);
     
     /**
      * 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 <code>isAvailable()</code> to see if it is there.
      * 
      * Note also that the message has no way of arriving on the list 
      * during this call unless the <code>Processor</code> is running 
      * as a thread, or unless some other thread is calling cycle().   
      *      
      * @param theAckId
      * @param theTimeoutMillis milliseconds until the call times out
      *      and returns null if the desired message is not available. 
      * @return the incoming message with the given ack ID, or null 
      *      if the call times out. 
      */
     public Transportable receive(String theAckId, long theTimeoutMillis) throws HL7Exception;
     
     /**
      * @return the operational context of this protocol instance 
      */
     public ProcessorContext getContext();
 
     /**
      * Request that the processor stop running and clean up any resources and worker threads it has started
      */
     public void stop();
 
     
 }

1		/*
2		* Created on 16-Apr-2004
3		*/
4		package ca.uhn.hl7v2.protocol;
5
6		import ca.uhn.hl7v2.HL7Exception;
7
8		/**
9		* Encapsulates both the client and server roles of the HL7-defined
10		* "original mode" and "enhanced mode" processing rules. See
11		* HL7 v2.5 chapter 2 for specifications.
12		*
13		* @author <a href="mailto:bryan.tripp@uhn.on.ca">Bryan Tripp</a>
14		* @version $Revision: 1.1 $ updated on $Date: 2007-02-19 02:24:38 $ by $Author: jamesagnew $
15		*/
16		public interface Processor {
17
18		/**
19		* Always send acknowledgement (in MSH-15 and 16)
20		*/
21		public static final String AL = "AL";
22
23		/**
24		* Never send acknowledgement (in MSH-15 and 16)
25		*/
26		public static final String NE = "NE";
27
28		/**
29		* Send acknowledgement only on error / reject (in MSH-15 and 16)
30		*/
31		public static final String ER = "ER";
32
33		/**
34		* Send acknowledgement only on successful receipt (in MSH-15 and 16)
35		*/
36		public static final String SU = "SU";
37
38
39		/**
40		* Original mode: Application Accept - Enhanced mode: Application acknowledgment: Accept
41		*/
42		public static final String AA = "AA";
43
44		/**
45		* Original mode: Application Error - Enhanced mode: Application acknowledgment: Error
46		*/
47		public static final String AE = "AE";
48		/**
49		* Original mode: Application Reject - Enhanced mode: Application acknowledgment: Reject
50		*/
51		public static final String AR = "AR";
52
53		/**
54		* Enhanced mode: Accept acknowledgment: Commit Accept
55		*/
56		public static final String CA = "CA";
57
58		/**
59		* Enhanced mode: Accept acknow ledgment: Commit Error
60		*/
61		public static final String CE = "CE";
62
63		/**
64		* Enhanced mode: Accept acknowledgment: Commit Reject
65		*/
66		public static final String CR = "CR";
67
68
69		/**
70		* Sends a message to a remote system via an underlying
71		* <code>TransportLayer</code>.
72		*
73		* If the message specifies that an accept ACK is required (under enhanced mode
74		* processing rules) then this method may retry if transmission does not appear
75		* to be successful. The call to this method blocks while this is happening.
76		* Retries are attempted if a CR message is received, or if no message is received
77		* in the specified time frame. If a CE is received, an exception is thrown. If
78		* a CA is received, the call returns quietly.
79		*
80		* If no accept ack is required, this method returns immediately after attempting to
81		* send a message, throwing an exception only if there is an immediate problem (eg the
82		* server can't be contacted).
83		*
84		* If an accept ack is required only on error, the method waits for maxRetries *
85		* retryItervalMillis for an error to be returned, and assumes that there is no error
86		* if none appears in that time. The message is not actually resent while waiting for an
87		* error ACK.
88		*
89		* @param theMessage the message to send
90		* @param maxRetries note that this should be a small value if you demand an accept ack only
91		* on error
92		* @param retryIntervalMillis note that this should be a small value if you demand an accept ack only
93		* on error
94		* @throws TransportException if there is an immediate problem trying to send the
95		* message.
96		*/
97		public void send(Transportable theMessage, int maxRetries, long retryIntervalMillis) throws HL7Exception;
98
99		/**
100		* Indicates that the calling thread expects a message with a certain ack
101		* ID. If this message arrives within the specified period of time, it will
102		* be held in an inbound list instead of being passed on to an
103		* <code>Application</code>. If a message is in this list it <code>isAvailable()</code>
104		* and can be had via <code>receive()</code>
105		*
106		* @param theAckId the acknowledgement ID of the message
107		* @param thePeriodMillis time span during which the message should be kept if received
108		*/
109		public void reserve(String theAckId, long thePeriodMillis);
110
111		/**
112		* <p>Performs a single iteration of the receiving-side
113		* of the HL7 original mode or enhanced mode processing rules
114		* (see HL7 Standard v2.5 Chapter 2; the choice of rules
115		* is determined by message values). Steps in the process are
116		* as follows: </p>
117		*
118		* 1. TransportLayer.receive() is called to get the next message <br>
119		* 2. Validation is performed and the message is stored locally. <br>
120		* 2. If the message requires an accept ACK, then an accept, reject,
121		* or error message is returned as appropriate <br>
122		* 3. If the message is an accept ack, it is added to a local list that
123		* can be accessed by the send() method <br>
124		* 4. If the message has been reserved, it is added to the available message
125		* list. <br>
126		* 5. Otherwise it is sent to an Application.
127		*
128		* @param expectingAck is passed to TransportLayer.receive(), and may determine
129		* where the message is read from (eg different sockets may be used for
130		* commit-level ACKs). Note that this call blocks until a message is ready
131		* at the specified location, so to run the Processor continuously,
132		* separate threads are needed to call cycle() with true and false args.
133		*/
134		public void cycle(boolean expectingAck) throws HL7Exception;
135
136		/**
137		* @param theAckId the acknowledgement ID of an expected message
138		* @return true if the message has come in and has been saved in the
139		* inbound message list
140		*/
141		public boolean isAvailable(String theAckId);
142
143		/**
144		* Gets the message with the given acknowledgement ID from
145		* the incoming message list. This method blocks until the
146		* message appears on the list. If you don't want to block,
147		* call <code>isAvailable()</code> to see if it is there.
148		*
149		* Note also that the message has no way of arriving on the list
150		* during this call unless the <code>Processor</code> is running
151		* as a thread, or unless some other thread is calling cycle().
152		*
153		* @param theAckId
154		* @param theTimeoutMillis milliseconds until the call times out
155		* and returns null if the desired message is not available.
156		* @return the incoming message with the given ack ID, or null
157		* if the call times out.
158		*/
159		public Transportable receive(String theAckId, long theTimeoutMillis) throws HL7Exception;
160
161		/**
162		* @return the operational context of this protocol instance
163		*/
164		public ProcessorContext getContext();
165
166		/**
167		* Request that the processor stop running and clean up any resources and worker threads it has started
168		*/
169		public void stop();
170
171
172		}