public interface OutboundRequestIterator
OutboundRequestinstances to use for attempting to send a particular request to a remote communication endpoint.
As long as
next method can be invoked to initiate an attempt
to make the request. If successful, the
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
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
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
getDeliveryStatus on the
OutboundRequest might aid in making that
OutboundRequestIterator is likely to
support making only one request attempt, in which case after one
next (successful or not),
hasNext will return
false. Reasons that
OutboundRequestIterator might support multiple
request attempts include:
hasNextmethod should not return
trueafter successive failed request attempts indefinitely. The request retry mechanism provided by
OutboundRequestIteratoris 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
to never return
true, in which case the
OutboundRequestIterator does not support initiating
even one attempt to send the request.
OutboundRequestIterator is not guaranteed to be
safe for concurrent use by multiple threads.
|Modifier and Type||Method and Description|
Initiates an attempt to communicate the request to the remote endpoint.
trueif this iterator supports making at least one more attempt to communicate the request, and
next has been invoked on this iterator and
the previous invocation of
next returned an
OutboundRequest, then this method should not be
invoked until that
OutboundRequest has been used
to attempt to communicate the request and a failure has
The security context in which this method is invoked may be
used for subsequent verification of security permissions; see
next method specification for more details.
trueif this iterator supports making another attempt to communicate the request, and
OutboundRequest next() throws IOException
If successful, this method returns an
OutboundRequest to use to write the request data
and read the response. Even if this method throws an
IOException or a
SecurityException, the iteration of
attempts to communicate the request may continue with another
The implementation verifies that the user's security context
has all of the security permissions necessary to communicate
the current request attempt with the remote endpoint and to
satisfy any required constraints, as appropriate to the
implementation of this interface. The implementation is
allowed, however, to indicate failure of such a permission
check by either throwing a
this method or, after returning an
from this method, throwing a
from some subsequent operation on the
OutboundRequest or its streams. If such a
SecurityException is thrown, request data must not
have been transmitted to the server (that is, if an
OutboundRequest has been returned, its
false), and the client's identity must
not have been revealed to the server.
Also, the implementation of this method or the returned
OutboundRequest must eventually verify that the
client and server have the requisite principals and credentials
to satisfy any required constraints and if not, throw an
IOException. If such an
is thrown, request data must not have been transmitted to the
In verifying any such permission requirement or credential,
the implementation is allowed to use the security context in
effect for this or any previous invocation of a method on this
iterator or the security context in effect for any operation on
OutboundRequest returned by this or any
previous invocation of this method on this iterator.
Therefore, this iterator and the
instances that it produces should be used in a uniform security
OutboundRequestto use to write the request data and read the response
NoSuchElementException- if this iterator does not support making another attempt to communicate the request (that is, if
IOException- if an I/O exception occurs while performing this operation; in this event, the recipient may have received an indication of the request initiation attempt
SecurityException- if the user does not have the permissions necessary to communicate with the remote endpoint
Copyright 2007-2013, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.