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.connection
Interface Connection

public interface Connection

Represents an established client-side connection. For example, a TCP-based `Connection` implementation typically contains a `Socket`.

`Connection` is implemented by connection-based `Endpoint` implementations that use `ConnectionManager` for managing connections. A `Connection` is created by the implementation for newly-established connections and is obtained by a `ConnectionManager` from its `ConnectionEndpoint`'s `connect` methods.

Since:
  2.0

Method Summary
`void` | `close()` Closes this connection.
`SocketChannel` | `getChannel()` Returns a socket channel that performs I/O on this connection, or `null` if no socket channel is available.
`InputStream` | `getInputStream()` Returns an input stream that reads data from this connection.
`OutputStream` | `getOutputStream()` Returns an output stream that writes data to this connection.
`InvocationConstraints` | `getUnfulfilledConstraints(OutboundRequestHandle handle)` Implements `OutboundRequest.getUnfulfilledConstraints` for a request with the specified handle.
`void` | `populateContext(OutboundRequestHandle handle, Collection context)` Populates the supplied collection with context information representing a request with the specified handle.
`IOException` | `readResponseData(OutboundRequestHandle handle, InputStream stream)` Reads from the specified stream any per-response data required by this connection for a request with the specified handle.
`void` | `writeRequestData(OutboundRequestHandle handle, OutputStream stream)` Writes to the specified stream any per-request data required by this connection for a request with the specified handle.

Method Detail

### getInputStream

    public InputStream getInputStream()
                               throws IOException

  Returns an input stream that reads data from this connection.

  Returns:
    an input stream that reads data from this connection
  Throws:
    `IOException` - if an I/O exception occurs

### getOutputStream

    public OutputStream getOutputStream()
                                 throws IOException

  Returns an output stream that writes data to this connection.

  Returns:
    an output stream that writes data to this connection
  Throws:
    `IOException` - if an I/O exception occurs

### getChannel

    public SocketChannel getChannel()

  Returns a socket channel that performs I/O on this connection, or `null` if no socket channel is available. If a non-`null` socket channel is returned, it is connected.

  Returns:
    a socket channel that performs I/O on this connection, or `null`

### populateContext

    public void populateContext(OutboundRequestHandle handle,
                                Collection context)

  Populates the supplied collection with context information representing a request with the specified handle. This method is used to implement `OutboundRequest.populateContext` for such requests; the context may also be populated by the connection manager.

  Parameters:
    `handle` - the handle for the request
    `context` - the context collection to populate
  Throws:
    `IllegalArgumentException` - if the specified handle was not created for use with a connection endpoint equivalent to the one used to create this connection
    `NullPointerException` - if `handle` or `context` is `null`
    `UnsupportedOperationException` - if `context` is unmodifiable

### getUnfulfilledConstraints

    public InvocationConstraints getUnfulfilledConstraints(OutboundRequestHandle handle)

  Implements `OutboundRequest.getUnfulfilledConstraints` for a request with the specified handle.

  Parameters:
    `handle` - the handle for the request
  Returns:
    the constraints for the request that must be partially or fully implemented by higher layers
  Throws:
    `IllegalArgumentException` - if the specified handle was not created for use with a connection endpoint equivalent to the one used to create this connection
    `NullPointerException` - if `handle` is `null`

### writeRequestData

    public void writeRequestData(OutboundRequestHandle handle,
                                 OutputStream stream)
                          throws IOException

  Writes to the specified stream any per-request data required by this connection for a request with the specified handle.

  This method is invoked by `ConnectionManager` with the request output stream of the `OutboundRequest` that it creates for the request. This method can be used, for example, to convey per-request information about delegation, client authentication, or client privileges.

  There may be multiple requests in progress concurrently over this connection, and data written to the specified stream may be buffered and multiplexed with data from other requests before being written to this connection's underlying output stream. Therefore, this method should only write data to the specified stream and must not read any data from this connection's underlying input stream; data can, however, be subsequently read with `readResponseData`.

  Parameters:
    `handle` - the handle for the request
    `stream` - the request output stream of the request
  Throws:
    `IOException` - if an I/O exception occurs
    `SecurityException` - if a security exception occurs
    `IllegalArgumentException` - if the specified handle was not created for use with a connection endpoint equivalent to the one used to create this connection
    `NullPointerException` - if `handle` or `stream` is `null`

### readResponseData

    public IOException readResponseData(OutboundRequestHandle handle,
                                        InputStream stream)
                                 throws IOException

  Reads from the specified stream any per-response data required by this connection for a request with the specified handle.

  This method returns `null` if the information read (if any) indicates that the constraints are satisfied, and it returns an exception if the constraints could not be satisfied. If an exception is returned rather than thrown, the delivery status of a corresponding `OutboundRequest` will be `false`.

  This method is invoked by `ConnectionManager` with the response input stream of the `OutboundRequest` that it creates for the request and the same handle that was passed to `writeRequestData`. This method can be used to read information produced by `ServerConnection.processRequestData` in response to the information sent by `writeRequestData`.

  There may be multiple requests in progress concurrently over this connection, and data read from the specified stream may have been buffered and multiplexed with data from other requests being read from this connection's underlying input stream. Therefore, this method should only read data from the specified stream and must not write any data to this connection's underlying output stream.

  Parameters:
    `handle` - the handle for the request
    `stream` - the response input stream of the request
  Returns:
    `null` if the constraints are satisfied, or an exception if the constraints could not be satisfied
  Throws:
    `IOException` - if an I/O exception occurs
    `SecurityException` - if a security exception occurs
    `IllegalArgumentException` - if the specified handle was not created for use with a connection endpoint equivalent to the one used to create this connection
    `NullPointerException` - if `handle` or `stream` is `null`

### close

    public void close()
               throws IOException

  Closes this connection.

  Throws:
    `IOException` - if an I/O exception occurs

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