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 OutboundRequest

public interface OutboundRequest

Represents a request that is being sent and the corresponding response received in reply.

An `OutboundRequest` can be used to write out the contents of the request and to read in the response.

The communication protocol used by the implementation of this interface must guarantee that for each instance of this interface, any request data must only be delivered to the recipient (in the form of an `InboundRequest` passed to `RequestDispatcher.dispatch`) at most once. The `getDeliveryStatus` method can be used to determine whether or not at least partial delivery of the request might have occurred.

When finished using an `OutboundRequest`, in order to allow the implementation to free resources associated with the request, users should either invoke `close` on the streams returned by the `getRequestOutputStream` and `getResponseInputStream` methods, or invoke the `abort` method.

Since:
  2.0
See Also:
  `InboundRequest`

Method Summary
`void` | `abort()` Terminates this request, freeing all associated resources.
`boolean` | `getDeliveryStatus()` Returns `false` if it is guaranteed that no data written for this request has been processed by the recipient.
`OutputStream` | `getRequestOutputStream()` Returns an `OutputStream` to write the request data to.
`InputStream` | `getResponseInputStream()` Returns an `InputStream` to read the response data from.
`InvocationConstraints` | `getUnfulfilledConstraints()` Returns the requirements that must be at least partially implemented by higher layers in order to fully satisfy the requirements for this request.
`void` | `populateContext(Collection context)` Populates the supplied collection with context information representing this request.

Method Detail

### populateContext

    public void populateContext(Collection context)

  Populates the supplied collection with context information representing this request.

  Parameters:
    `context` - the context collection to populate
  Throws:
    `NullPointerException` - if `context` is `null`
    `UnsupportedOperationException` - if `context` is unmodifiable

### getUnfulfilledConstraints

    public InvocationConstraints getUnfulfilledConstraints()

  Returns the requirements that must be at least partially implemented by higher layers in order to fully satisfy the requirements for this request. This method may also return preferences that must be at least partially implemented by higher layers in order to fully satisfy some of the preferences for this request.

  For any given constraint, there must be a clear delineation of which aspects (if any) must be implemented by the transport layer. This method must not return a constraint (as a requirement or a preference, directly or as an element of another constraint) unless this request implements all of those aspects. Also, this method must not return a constraint for which all aspects must be implemented by the transport layer. Most of the constraints in the `net.jini.core.constraint` package must be fully implemented by the transport layer and thus must not be returned by this method; the one exception is `Integrity`, for which the transport layer is responsible for the data integrity aspect and higher layers are responsible for the code integrity aspect.

  For any `ConstraintAlternatives` in the constraints for this request, this method should only return a corresponding constraint if all of the alternatives satisfied by this request need to be at least partially implemented by higher layers in order to be fully satisfied.

  Returns:
    the constraints for this request that must be partially or fully implemented by higher layers

### getRequestOutputStream

    public OutputStream getRequestOutputStream()

  Returns an `OutputStream` to write the request data to. The sequence of bytes written to the returned stream will be the sequence of bytes sent as the body of this request.

  After the entirety of the request has been written to the stream, the stream's `close` method must be invoked to ensure complete delivery of the request. It is possible that none of the data written to the returned stream will be delivered before `close` has been invoked (even if the stream's `flush` method had been invoked at any time). Note, however, that some or all of the data written to the stream may be delivered to (and processed by) the recipient before the stream's `close` method has been invoked.

  After the stream's `close` method has been invoked, no more data may be written to the stream; writes subsequent to a `close` invocation will fail with an `IOException`.

  If this method is invoked more than once, it will always return the identical stream object that it returned the first time (although the stream may be in a different state than it was upon return from the first invocation).

  Returns:
    the output stream to write request data to

### getResponseInputStream

    public InputStream getResponseInputStream()

  Returns an `InputStream` to read the response data from. The sequence of bytes produced by reading from the returned stream will be the sequence of bytes received as the response data. When the entirety of the response has been successfully read, reading from the stream will indicate an EOF.

  Users of an `OutboundRequest` must not expect any data to be available from the returned stream before the `close` method has been invoked on the stream returned by `getRequestOutputStream`; in other words, the user's request/response protocol must not require any part of a request to be a function of any part of its response.

  It is possible, however, for data to be available from the returned stream before the `close` method has been invoked on, or even before the entirety of the request has been written to, the stream returned by `getRequestOutputStream`. Because such an early response might indicate, depending on the user's request/response protocol, that the recipient will not consider the entirety of the request, perhaps due to an error or other abnormal condition, the user may wish to process it expeditiously, rather than continuing to write the remainder of the request.

  Invoking the `close` method of the returned stream will cause any subsequent read operations on the stream to fail with an `IOException`, although it will not terminate this request as a whole; in particular, the request may still be subsequently written to the stream returned by the `getRequestOutputStream` method. After `close` has been invoked on both the returned stream and the stream returned by `getRequestOutputStream`, the implementation may free all resources associated with this request.

  If this method is invoked more than once, it will always return the identical stream object that it returned the first time (although the stream may be in a different state than it was upon return from the first invocation).

  Returns:
    the input stream to read response data from

### getDeliveryStatus

    public boolean getDeliveryStatus()

  Returns `false` if it is guaranteed that no data written for this request has been processed by the recipient. This guarantee remains valid until any subsequent I/O operation has been attempted on this request. If this method returns `true`, then data written for this request may have been at least partially processed by the recipient (the `RequestDispatcher` receiving the corresponding `InboundRequest`).

  Returns:
    `false` if data written for this request has definitely not been processed by the recipient, and `true` if data written for this request may have been at least partially processed by the recipient

### abort

    public void abort()

  Terminates this request, freeing all associated resources.

  This method may be invoked at any stage of the processing of the request.

  After this method has been invoked, I/O operations on the streams returned by the `getRequestOutputStream` and `getResponseInputStream` methods will fail with an `IOException`, except some operations that may succeed because they only affect data in local I/O buffers.

  If this method is invoked before the `close` method has been invoked on the stream returned by `getRequestOutputStream`, there is no guarantee that any or none of the data written to the stream so far will be delivered; the implication of such an invocation of this method is that the user is no longer interested in the successful delivery of the request.

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