01: package dalma;
02:
03: import java.util.Date;
04: import java.util.Iterator;
05:
06: /**
07: * {@link Iterator} that enumerates the replies received to a message
08: * that was sent out from an {@link EndPoint}.
09: *
10: * <p>
11: * In a workflow, it's common for your program to send out a 'message'
12: * (such as an e-mail, JMS message, etc), then wait for replies to it.
13: * {@link ReplyIterator} defines a programming pattern that collects
14: * all the replies in an easy way.
15: *
16: * <p>
17: * This message exchange pattern (MEP) is commonly seen across
18: * many different messaging mechanisms, so {@link ReplyIterator} is parameterized
19: * with the type {@code T} that represents the type of a reply.
20: *
21: * <p>
22: * Replies are received over the time, so at some point your application
23: * has to decide that you are not going to wait for any more replies.
24: * For this purpose, a {@link ReplyIterator} has an <b>expiration date</b>.
25: * Replies received beyond this expiration date will not be returned from
26: * a {@link ReplyIterator} (what happens to such messages depend on the endpoint
27: * implementation.) Alternatively, you can call {@link #dispose()} method
28: * any time to discard the iterator. This allows the implementation to possibly
29: * clean up the relevant resources.
30: *
31: * <p>
32: * Every time you call the iterator's {@link Iterator#hasNext() hasNext} method,
33: * it checks if a reply is received. If not, the conversation suspends
34: * and then resumes only when either (1) a reply is received or (2) the expiration date
35: * of this iterator is reached.
36: *
37: * <p>
38: * If a reply is received, {@link #hasNext() hasNext} method returns true,
39: * and the reply can be fetched by calling {@link #next() next} method,
40: * just like a normal {@link Iterator}.
41: *
42: * <p>
43: * If the expiration date is reached, the {@link #hasNext() hasNext} method
44: * returns false, indicating that it will not wait for another message.
45: *
46: * <p>
47: * Together, this allows the calling conversation to efficiently handle
48: * all the reply messages received during a particular time period, then
49: * move on to do something else.
50: *
51: * @author Kohsuke Kawaguchi
52: */
53: public interface ReplyIterator<T> extends Iterator<T> {
54: /**
55: * Gets the expiration date of this iterator.
56: *
57: * Once this date is reached, the iterator no longer waits for new messages,
58: * and simply return <tt>false</tt> from {@link #hasNext()} method (unless
59: * there are messages that are received before the expiration date, which are
60: * not read yet.)
61: */
62: Date getExpirationDate();
63:
64: /**
65: * Always throws {@link UnsupportedOperationException}.
66: */
67: void remove() throws UnsupportedOperationException;
68:
69: /**
70: * Possibly clean up resources allocated for this object.
71: *
72: * <p>
73: * When an application decides that it no longer needs to check
74: * any message from this {@link ReplyIterator}, it may call this
75: * method to let the implementation release resources earlier.
76: *
77: * <p>
78: * This method is optional for both callers and callees;
79: * a caller is not required to invoke this method, and the callee
80: * is not required to take any action.
81: *
82: * <p>
83: * This method can be invoked multiple times.
84: */
85: void dispose();
86: }
|