OutboundConnectionCachepublic interface OutboundConnectionCache implements ConnectionCache| 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:
- A Connection must implement a close() method. This is called when idle
connections are reclaimed.
- A Connection must be usable as a HashMap key.
- 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.
- The ContactInfo must be usable as a HashMap key.
- 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. |
| Methods Summary |
|---|
| public boolean | canCreateNewConnection(ContactInfo cinfo)Determine whether a new connection could be created by the
ConnectionCache or not.
| | public C | get(ContactInfo cinfo, ConnectionFinder finder)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)
- 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.
| | public C | get(ContactInfo cinfo)Behaves the same as get( ContactInfo, ConnectionFinder )
except that no connection finder is provided, so that step is
ignored.
| | public int | maxParallelConnections()Configured maximum number of connections supported per ContactInfo.
| | public 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.
| | public 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.
|
|
