Produces {@link OutboundRequest} instances to use for attempting tosend a particular request to a remote communication endpoint.
As long as {@link #hasNext hasNext} returns true
,the {@link #next next} method can be invoked to initiate an attemptto make the request. If successful, the next
method returns an OutboundRequest
to use to write the request data and read the response.
If the request communication attempt fails, such as if the next
invocation throws an exception or if a subsequent I/O operation on the returned OutboundRequest
or its streams throws an exception, then if hasNext
returns true
again, the next
method can be invoked again to retry the request attempt. This process of retrying failed request attempts can repeat as long as hasNext
returns true
after the previous failed request attempt.
Note that it is the user's responsibility to abstain from retrying a request attempt if doing so might violate any applicable guarantees of at most once execution semantics (invoking {@link OutboundRequest#getDeliveryStatus getDeliveryStatus} on theprevious OutboundRequest
might aid in making that determination).
A typical OutboundRequestIterator
is likely to support making only one request attempt, in which case after one invocation of next
(successful or not), hasNext
will return false
. Reasons that an OutboundRequestIterator
might support multiple request attempts include:
- if the remote endpoint implementation features multiple communication mechanism alternatives to attempt or
- if the implementation can ascertain that the nature of the previous request attempt failure indicates that it would be very unlikely to reoccur in a subsequent attempt.
The
hasNext
method should not return
true
after successive failed request attempts indefinitely. The request retry mechanism provided by
OutboundRequestIterator
is not intended for implementing a strategy of general retry of the same communication mechanism after indeterminate failures.
Note that it is permitted, although unlikely, for an OutboundRequestIterator
's hasNext
method to never return true
, in which case the OutboundRequestIterator
does not support initiating even one attempt to send the request.
An OutboundRequestIterator
is not guaranteed to be safe for concurrent use by multiple threads.
@author Sun Microsystems, Inc.
@see Endpoint
@since 2.0