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