Connection (Apache River v3.0.0 Specification-only API Documentation)

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

Author:

Sun Microsystems, Inc.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
void close()
    throws IOException
```
    Closes this connection.
    
    Throws:
    
    IOException - if an I/O exception occurs

Interface Connection

Method Summary

Method Detail

getInputStream

getOutputStream

getChannel

populateContext

getUnfulfilledConstraints

writeRequestData

readResponseData

close