View Javadoc

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 }