net.jini.jeri.connection
Interface ConnectionEndpoint


public interface ConnectionEndpoint

Represents a remote communication endpoint to establish connections to. For example, a TCP-based ConnectionEndpoint implementation typically contains the remote host address and TCP port to connect to.

ConnectionEndpoint is implemented by connection-based Endpoint implementations that use ConnectionManager for managing connections. A ConnectionManager is created for a given ConnectionEndpoint, and it uses that ConnectionEndpoint to choose an established connection for a given request or to establish a new connection for a given request.

An instance of this interface should implement Object.equals to obey the guidelines that are specified for equals methods of Endpoint instances.

Since:
2.0
Author:
Sun Microsystems, Inc.

Method Summary
 Connection connect(OutboundRequestHandle handle)
          Returns a new connection that can be used to send a request for the specified handle.
 Connection connect(OutboundRequestHandle handle, Collection active, Collection idle)
          Returns an existing or new connection that can be used to send a request for the specified handle, or null if a new connection needs to be created in a way that requires synchronous I/O.
 

Method Detail

connect

Connection connect(OutboundRequestHandle handle)
                   throws IOException
Returns a new connection that can be used to send a request for the specified handle.

The actual network connection might not be completely established when this method returns; connection establishment (including any permission checks required) may proceed asynchronously.

Either this method or the returned connection must eventually check and throw a SecurityException if the calling thread (at the point of the check) does not have the requisite permissions to send an outbound request for the specified handle. If an exception is thrown, data written to the connection's output stream must not have been transmitted to the server, and the client's identity must not have been revealed to the server.

Either this method or the returned connection must eventually check and throw an IOException if the client or server does not have the requisite principals and credentials to allow the client to send an outbound request for the specified handle. If an exception is thrown, data written to the connection's output stream must not have been transmitted to the server.

Parameters:
handle - the handle for the request
Returns:
a new connection that can be used to send a request for the specified handle
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 an equivalent connection endpoint
NullPointerException - if handle is null

connect

Connection connect(OutboundRequestHandle handle,
                   Collection active,
                   Collection idle)
Returns an existing or new connection that can be used to send a request for the specified handle, or null if a new connection needs to be created in a way that requires synchronous I/O.

This method is passed any existing connections, both active and idle, that might be suitable for use. The active connections have other requests in progress; the idle connections do not. All other things being equal, an active connection should be chosen over an idle one, and an idle connection should be chosen over creating a new one. An active (or idle) connection, however, might be less suitable than an idle (or new) one for various reasons, such as being too expensive relative to the constraints that need to be satisfied.

This method is permitted to alter the state of an idle connection (for example, to renegotiate the constraints in force), but any I/O for that purpose must be performed either asynchronously or at subsequent I/O operations on the connection, and it must be completed before any data written to the connection's output stream is actually transmitted. An implementation that performs any such I/O must distinguish it from I/O performed on the connection's streams.

This method is permitted to return a new connection, but it must not perform any synchronous I/O to establish the connection; such I/O must be performed either asynchronously or at subsequent I/O operations on the connection. If synchronous I/O is required to create a new connection, this method should return null.

This method should not assume that the collections are modifiable and should not assume that their contents will remain valid after this method returns.

Either this method or the returned connection must eventually check and throw a SecurityException if the calling thread (at the point of the check) does not have the requisite permissions to send an outbound request for the specified handle. If an exception is thrown, data written to the connection's output stream must not have been transmitted to the server, and the client's identity must not have been revealed to the server.

The returned connection must eventually check and throw an IOException if the client or server does not have the requisite principals and credentials to allow the client to send an outbound request for the specified handle. If an exception is thrown, data written to the connection's output stream must not have been transmitted to the server.

If an existing active connection is returned, this method must ensure that the security and credential checks for the current request will not cause the checks for existing active requests to unnecessarily fail or to incorrectly succeed, and vice versa. Therefore, in practice, this method should only return an existing active connection if all of the security and credential checks are made before this method returns.

Note that a ConnectionManager never makes concurrent invocations of this method; implementations should take that into consideration when deciding if and how long this method should block.

Parameters:
handle - the handle for the request
active - the connections with requests in progress
idle - the connections with no requests in progress
Returns:
a connection that can be used to send an outbound request for the specified handle, or null
Throws:
SecurityException - if a security exception occurs
IllegalArgumentException - if the specified handle was not created for use with an equivalent connection endpoint, or a connection in either collection was not created by an equivalent connection endpoint
NullPointerException - if any argument is null or any element of either collection is null


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