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 String AL = "AL";
22
23 /**
24 * Never send acknowledgement (in MSH-15 and 16)
25 */
26 String NE = "NE";
27
28 /**
29 * Send acknowledgement only on error / reject (in MSH-15 and 16)
30 */
31 String ER = "ER";
32
33 /**
34 * Send acknowledgement only on successful receipt (in MSH-15 and 16)
35 */
36 String SU = "SU";
37
38
39 /**
40 * Original mode: Application Accept - Enhanced mode: Application acknowledgment: Accept
41 */
42 String AA = "AA";
43
44 /**
45 * Original mode: Application Error - Enhanced mode: Application acknowledgment: Error
46 */
47 String AE = "AE";
48 /**
49 * Original mode: Application Reject - Enhanced mode: Application acknowledgment: Reject
50 */
51 String AR = "AR";
52
53 /**
54 * Enhanced mode: Accept acknowledgment: Commit Accept
55 */
56 String CA = "CA";
57
58 /**
59 * Enhanced mode: Accept acknow ledgment: Commit Error
60 */
61 String CE = "CE";
62
63 /**
64 * Enhanced mode: Accept acknowledgment: Commit Reject
65 */
66 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 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 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 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 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 Transportable receive(String theAckId, long theTimeoutMillis) throws HL7Exception;
160
161 /**
162 * @return the operational context of this protocol instance
163 */
164 ProcessorContext getContext();
165
166 /**
167 * Request that the processor stop running and clean up any resources and worker threads it has started
168 */
169 void stop();
170
171
172 }