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

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

    public 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

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

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