The implementation of a thread-safe client connection manager.
The implementation is structured into three areas, as illustrated by the diagram above. Facing the application is the Manager (green), which internally maintains a Pool (yellow) of connections and waiting threads. Both Manager and Pool rely on Operations (cyan) to provide the actual connections.
In order to allow connection garbage collection, it is imperative that hard object references between the areas are restricted to the relations indicated by arrows in the diagram:
The following table shows a selection of classes and interfaces, and their assignment to the three areas.
The Manager area has implementations for the connection management
The latter is an adapter from managed to operated connections, based on a
The Pool area shows an abstract pool class
and a concrete implementation
which uses the same basic algorithm as the
in HttpClient 3.x.
A pool contains instances of
Most other classes in this package also belong to the Pool area.
In the Operations area, you will find only the interfaces for operated connections as defined in the org.apache.http.conn package. The connection manager will work with all correct implementations of these interfaces. This package therefore does not define anything specific to the Operations area.
As you have surely noticed, the
appears in both the Manager and Pool areas.
This is where things get tricky for connection garbage collection.
A connection pool may start a background thread to implement cleanup. In that case, the connection pool will not be garbage collected until it is shut down, since the background thread keeps a hard reference to the pool. The pool itself keeps hard references to the pooled entries, which in turn reference idle connections. Neither of these is subject to garbage collection. Only the shutdown of the pool will stop the background thread, thereby enabling garbage collection of the pool objects.
A pool entry that is passed to an application by means of a connection adapter will move from the Pool area to the Manager area. When the connection is released by the application, the manager returns the entry back to the pool. With that step, the pool entry moves from the Manager area back to the Pool area. While the entry is in the Manager area, the pool MUST NOT keep a hard reference to it.
The purpose of connection garbage collection is to detect when an
application fails to return a connection. In order to achieve this,
the only hard reference to the pool entry in the Manager area is
in the connection wrapper. The manager will not keep a hard reference
to the connection wrapper either, since that wrapper is effectively
moving to the Application area.
If the application drops it's reference to the connection wrapper,
that wrapper will be garbage collected, and with it the pool entry.
In order to detect garbage collection of pool entries handed out to the application, the pool keeps a weak reference to the entry. Instances of
combine the weak reference with information about the route for
which the pool entry was allocated. If one of these entry references
becomes stale, the pool can accommodate for the lost connection.
This is triggered either by a background thread waiting for the
references to be queued by the garbage collector, or by the
application calling a
method of the connection manager.
Basically the same trick is used for detecting garbage collection of the connection manager itself. The pool keeps a weak reference to the connection manager that created it. However, this will work only if there is a background thread to detect when that reference is queued by the garbage collector. Otherwise, a finalizer of the connection manager will shut down the pool and release it's resources.