| Iterator that enumerates the replies received to a message
that was sent out from an
EndPoint .
In a workflow, it's common for your program to send out a 'message'
(such as an e-mail, JMS message, etc), then wait for replies to it.
ReplyIterator defines a programming pattern that collects
all the replies in an easy way.
This message exchange pattern (MEP) is commonly seen across
many different messaging mechanisms, so
ReplyIterator is parameterized
with the type
T that represents the type of a reply.
Replies are received over the time, so at some point your application
has to decide that you are not going to wait for any more replies.
For this purpose, a
ReplyIterator has an expiration date.
Replies received beyond this expiration date will not be returned from
a
ReplyIterator (what happens to such messages depend on the endpoint
implementation.) Alternatively, you can call
ReplyIterator.dispose() method
any time to discard the iterator. This allows the implementation to possibly
clean up the relevant resources.
Every time you call the iterator's
Iterator.hasNext hasNext method,
it checks if a reply is received. If not, the conversation suspends
and then resumes only when either (1) a reply is received or (2) the expiration date
of this iterator is reached.
If a reply is received,
ReplyIterator.hasNext() hasNext method returns true,
and the reply can be fetched by calling
ReplyIterator.next() next method,
just like a normal
Iterator .
If the expiration date is reached, the
ReplyIterator.hasNext() hasNext method
returns false, indicating that it will not wait for another message.
Together, this allows the calling conversation to efficiently handle
all the reply messages received during a particular time period, then
move on to do something else.
author:
Kohsuke Kawaguchi |