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 InboundRequest

public interface InboundRequest

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

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

Since:
  2.0
See Also:
  `OutboundRequest`, `RequestDispatcher`

Method Summary
`void` | `abort()` Terminates this request, freeing all associated resources.
`InvocationConstraints` | `checkConstraints(InvocationConstraints constraints)` Verifies that this request satisfies the transport layer aspects of all of the specified requirements, and returns the requirements that must be at least partially implemented by higher layers in order to fully satisfy the specified requirements.
`void` | `checkPermissions()` Verifies that the current security context has all of the security permissions necessary to receive this request.
`InputStream` | `getRequestInputStream()` Returns an `InputStream` to read the request data from.
`OutputStream` | `getResponseOutputStream()` Returns an `OutputStream` to write the response data to.
`void` | `populateContext(Collection context)` Populates the supplied collection with context information representing this request.

Method Detail

### checkPermissions

    public void checkPermissions()

  Verifies that the current security context has all of the security permissions necessary to receive this request.

  This method should be used when a particular shared mechanism is used to receive requests for a variety of interested parties, each with potentially different security permissions possibly more limited than those granted to the code managing the shared mechanism, so that the managing code can verify proper access control for each party.

  For example, a TCP-based `InboundRequest` implementation typically implements this method by invoking the `checkAccept` method of the current security manager (if any) with the client's host address and TCP port. An implementation that supports authentication typically checks that the current security context has the necessary `AuthenticationPermission` with `accept` action.

  Throws:
    `SecurityException` - if the current security context does not have the permissions necessary to receive this request

### checkConstraints

    public InvocationConstraints checkConstraints(InvocationConstraints constraints)
                                           throws UnsupportedConstraintException

  Verifies that this request satisfies the transport layer aspects of all of the specified requirements, and returns the requirements that must be at least partially implemented by higher layers in order to fully satisfy the specified requirements. This method may also return preferences that must be at least partially implemented by higher layers in order to fully satisfy some of the specified preferences.

  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 specified constraints, 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.

  The constraints actually in force may cause conditional constraints to have to be satisfied. For example, if the only requirement specified is `Delegation.YES` but the client was in fact authenticated, then the client must also have delegated to the server.

  The constraints passed to this method may include constraints based on relative time.

  Parameters:
    `constraints` - the constraints that must be satisfied
  Returns:
    the constraints that must be at least partially implemented by higher layers
  Throws:
    `UnsupportedConstraintException` - if the transport layer aspects of any of the specified requirements are not satisfied by this request
    `NullPointerException` - if `constraints` is `null`

### 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

### getRequestInputStream

    public InputStream getRequestInputStream()

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

  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 response may still be subsequently written to the stream returned by the `getResponseOutputStream` method. After `close` has been invoked on both the returned stream and the stream returned by `getResponseOutputStream`, 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 request data from

### getResponseOutputStream

    public OutputStream getResponseOutputStream()

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

  After the entirety of the response has been written to the stream, the stream's `close` method must be invoked to ensure complete delivery of the response. 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 has 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 response data to

### 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 `getRequestInputStream` and `getResponseOutputStream` 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 `getResponseOutputStream`, 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 response.

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