com.sun.corba.ee.spi.transport.connection

Interface OutboundConnectionCache<C extends Connection>

All Superinterfaces:

ConnectionCache<C>

All Known Implementing Classes:

OutboundConnectionCacheBlockingImpl, OutboundConnectionCacheImpl

public interface OutboundConnectionCache<C extends Connection>
extends ConnectionCache<C>

A concurrent mostly non-blocking connection cache. Here a Connection is an abstraction of a Socket or SocketChannel: basically some sort of resource that is expensive to acquire, and can be re-used freely. The cache maintains a loose upper bound on the number of cached connections, and reclaims connections as needed.

This cache places minimal requirements on the Connections that it contains:

1. A Connection must implement a close() method. This is called when idle connections are reclaimed.
2. A Connection must be usable as a HashMap key.
3. There must be a ContactInfo class that is used to create Connection instances. The ContactInfo class must support a create() method that returns a Connection.
4. The ContactInfo must be usable as a HashMap key.
5. All instances created from a ContactInfo are equal; that is, any request sent to a particular ContactInfo can used an instance created from that ContactInfo. For example, in the CORBA case, IP host and port is not always sufficient: we may also need the Codeset type that indicates how Strings are encoded. Basically, protocols (like GIOP) that bind session state to a Connection may need more than transport information in the ContactInfo.

Some simple methods are provided for monitoring the state of the cache: numbers of busy and idle connections, and the total number of connections in the cache.

Method Summary

Modifier and Type	Method and Description
boolean	canCreateNewConnection(ContactInfo<C> cinfo) Determine whether a new connection could be created by the ConnectionCache or not.
C	get(ContactInfo<C> cinfo) Behaves the same as get( ContactInfo, ConnectionFinder ) except that no connection finder is provided, so that step is ignored.
C	get(ContactInfo<C> cinfo, ConnectionFinder<C> finder) Return a Connection corresponding to the given ContactInfo.
int	maxParallelConnections() Configured maximum number of connections supported per ContactInfo.
void	release(C conn, int numResponseExpected) Release a Connection previously obtained from get.
void	responseReceived(C conn) Inform the cache that a response has been received on a particular connection.

Methods inherited from interface com.sun.corba.ee.spi.transport.connection.ConnectionCache

close, getCacheType, highWaterMark, numberOfBusyConnections, numberOfConnections, numberOfIdleConnections, numberOfReclaimableConnections, numberToReclaim

Method Detail

maxParallelConnections

int maxParallelConnections()

Configured maximum number of connections supported per ContactInfo.

canCreateNewConnection

boolean canCreateNewConnection(ContactInfo<C> cinfo)

Determine whether a new connection could be created by the ConnectionCache or not.

get

C get(ContactInfo<C> cinfo,
      ConnectionFinder<C> finder)
throws IOException

Return a Connection corresponding to the given ContactInfo. This works as follows:

• Call the finder. If it returns non-null, use that connection; (Note that this may be a new connection, created in the finder). The finder SHOULD NOT create a new connection if canCreateNewConnection returns false, but this is advisory.
• otherwise, Use an idle connection, if one is available;
• otherwise, create a new connection, if not too many connections are open;
• otherwise, use a busy connection.

Note that creating a new connection requires EITHER:

• there is no existing connection for the ContactInfo
• OR the total number of connections in the cache is less than the HighWaterMark and the number of connections for this ContactInfo is less than MaxParallelConnections.

We will always return a Connection for a get call UNLESS we have no existing connection and an attempt to create a new connection fails. In this case, the IOException thrown by ContactInfo.create is propagated out of this method.

It is possible that the cache contains connections that no longer connect to their destination. In this case, it is the responsibility of the client of the cache to close the broken connection as they are detected. Connection reclamation may also handle the cleanup, but note that a broken connection with pending responses will never be reclaimed.

Note that the idle and busy connection collections that are passed to the finder are unmodifiable collections. They have iterators that return connections in LRU order, with the least recently used connection first. This is done to aid a finder that wishes to consider load balancing in its determination of an appropriate connection.

Throws:

IOException

get

C get(ContactInfo<C> cinfo)
throws IOException

Behaves the same as get( ContactInfo, ConnectionFinder ) except that no connection finder is provided, so that step is ignored.

Throws:

IOException

release

void release(C conn,
             int numResponseExpected)

Release a Connection previously obtained from get. Connections that have been released as many times as they have been returned by get are idle; otherwise a Connection is busy. Some number of responses (usually 0 or 1) may be expected ON THE SAME CONNECTION even for an idle connection. We maintain a count of the number of outstanding responses we expect for protocols that return the response on the same connection on which the request was received. This is necessary to prevent reclamation of a Connection that is idle, but still needed to send responses to old requests.

responseReceived

void responseReceived(C conn)

Inform the cache that a response has been received on a particular connection. This must also be called in the event that no response is received, but the client times out waiting for a response, and decides to abandon the request.

When a Connection is idle, and has no pending responses, it is eligible for reclamation.