Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.jini.jeri
Interface OutboundRequestIterator

public interface OutboundRequestIterator

Produces `OutboundRequest` instances to use for attempting to send a particular request to a remote communication endpoint.

As long as `hasNext` returns `true`, the `next` method can be invoked to initiate an attempt to 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 `getDeliveryStatus` on the previous `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.

Since:
  2.0
See Also:
  `Endpoint`

Method Summary
`boolean` | `hasNext()` Returns `true` if this iterator supports making at least one more attempt to communicate the request, and `false` otherwise.
`OutboundRequest` | `next()` Initiates an attempt to communicate the request to the remote endpoint.

Method Detail

### hasNext

    public boolean hasNext()

  Returns `true` if this iterator supports making at least one more attempt to communicate the request, and `false` otherwise.

  If this method returns `true`, then it is guaranteed that the next invocation of `next` on this iterator will not throw a `NoSuchElementException`.

  If `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 occurred.

  The security context in which this method is invoked may be used for subsequent verification of security permissions; see the `next` method specification for more details.

  Returns:
    `true` if this iterator supports making another attempt to communicate the request, and `false` otherwise

### next

    public OutboundRequest next()
                         throws IOException

  Initiates an attempt to communicate the request to the remote endpoint.

  After an invocation of `hasNext` returns `true`, it is guaranteed that the next invocation of this method will not throw a `NoSuchElementException`.

  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 invocation of `hasNext`.

  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 `SecurityException` from this method or, after returning an `OutboundRequest` from this method, throwing a `SecurityException` 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 `getDeliveryStatus` method must return `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 `IOException` is thrown, request data must not have been transmitted to the server.

  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 the `OutboundRequest` returned by this or any previous invocation of this method on this iterator. Therefore, this iterator and the `OutboundRequest` instances that it produces should be used in a uniform security context.

  Returns:
    the `OutboundRequest` to use to write the request data and read the response
  Throws:
    `NoSuchElementException` - if this iterator does not support making another attempt to communicate the request (that is, if `hasNext` would return `false`)
    `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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved