public interface ConnectionEndpoint
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.
| Modifier and Type | Method and Description |
|---|---|
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. |
Connection connect(OutboundRequestHandle handle) throws IOException
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.
handle - the handle for the requestIOException - if an I/O exception occursSecurityException - if a security exception occursIllegalArgumentException - if the specified handle was
not created for use with an equivalent connection endpointNullPointerException - if handle is
nullConnection connect(OutboundRequestHandle handle, Collection active, Collection idle)
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.
handle - the handle for the requestactive - the connections with requests in progressidle - the connections with no requests in progressnullSecurityException - if a security exception occursIllegalArgumentException - 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 endpointNullPointerException - if any argument is
null or any element of either collection is
null