net.jini.jeri.connection
Interface ServerConnection


public interface ServerConnection

Represents an established server-side connection. For example, a TCP-based ServerConnection implementation typically contains a Socket.

ServerConnection is implemented by a connection-based ServerEndpoint implementation that uses ServerConnectionManager for managing connections. A ServerConnection is created by the implementation for newly-accepted connections and passed to the manager's handleConnection method.

Since:
2.0
Author:
Sun Microsystems, Inc.

Method Summary
 InvocationConstraints checkConstraints(InboundRequestHandle handle, InvocationConstraints constraints)
          Implements InboundRequest.checkConstraints for a request with the specified handle.
 void checkPermissions(InboundRequestHandle handle)
          Implements InboundRequest.checkPermissions for a request with the specified handle.
 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.
 void populateContext(InboundRequestHandle handle, Collection context)
          Populates the supplied collection with context information representing a request with the specified handle.
 InboundRequestHandle processRequestData(InputStream in, OutputStream out)
          Reads from the specified input stream any per-request data required by this connection for an inbound request, writes any required response data to the specified output stream, and returns a handle for the request.
 

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

processRequestData

InboundRequestHandle processRequestData(InputStream in,
                                        OutputStream out)
                                        throws IOException
Reads from the specified input stream any per-request data required by this connection for an inbound request, writes any required response data to the specified output stream, and returns a handle for the request.

This method is invoked by ServerConnectionManager with the request input stream and the response output stream of the InboundRequest that it creates for the request when the request is first received. This method reads information that was sent by Connection.writeRequestData and writes information to be read by Connection.readResponseData. This method can be used, for example, to process per-request information about delegation, client authentication, or client privileges.

If, for security reasons, this method determines that the request must not be processed further (for example, because client authentication failed), this method should close the response output stream and throw a SecurityException after writing any response data.

There may be multiple requests in progress concurrently over this connection, and data read from and written to the specified streams may be buffered and multiplexed with data from other requests on this connection's underlying streams. Therefore, this method should only read data from the request input stream and write data to the response output stream and must not otherwise read from or write to this connection's underlying streams.

Parameters:
in - the request input stream of the request
out - the response output stream of the request
Returns:
a handle to identify the request in later invocations on this connection
Throws:
NullPointerException - if in or out is null
IOException - if an I/O exception occurs
SecurityException - if a security exception occurs

checkPermissions

void checkPermissions(InboundRequestHandle handle)
Implements InboundRequest.checkPermissions for a request with the specified handle.

Parameters:
handle - the handle for the request
Throws:
SecurityException - if the current security context does not have the permissions necessary to receive the request
IllegalArgumentException - if the specified handle was not returned from this connection's processRequestData method
NullPointerException - if handle is null

checkConstraints

InvocationConstraints checkConstraints(InboundRequestHandle handle,
                                       InvocationConstraints constraints)
                                       throws UnsupportedConstraintException
Implements InboundRequest.checkConstraints for a request with the specified handle.

Parameters:
handle - the handle for the request
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
IllegalArgumentException - if the specified handle was not returned from this connection's processRequestData method
NullPointerException - if handle or constraints is null

populateContext

void populateContext(InboundRequestHandle handle,
                     Collection context)
Populates the supplied collection with context information representing a request with the specified handle. This method is used to implement InboundRequest.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 returned from this connection's processRequestData method
NullPointerException - if handle or context is null
UnsupportedOperationException - if context is unmodifiable

close

void close()
           throws IOException
Closes this connection.

Throws:
IOException - if an I/O exception occurs


Copyright 2007, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.