TSCCM package JavaDocs
git-svn-id: https://svn.apache.org/repos/asf/jakarta/httpcomponents/httpclient/trunk@564950 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Roland Weber
parent
29d8c269b9
commit
532fddb7aa
Binary file not shown.
|
After Width: | Height: | Size: 4.1 KiB |
|
|
@ -0,0 +1,204 @@
|
|||
<html>
|
||||
<head>
|
||||
<!--
|
||||
/*
|
||||
* $HeadURL$
|
||||
* $Revision$
|
||||
* $Date$
|
||||
*
|
||||
* ====================================================================
|
||||
* Licensed to the Apache Software Foundation (ASF) under one
|
||||
* or more contributor license agreements. See the NOTICE file
|
||||
* distributed with this work for additional information
|
||||
* regarding copyright ownership. The ASF licenses this file
|
||||
* to you under the Apache License, Version 2.0 (the
|
||||
* "License"); you may not use this file except in compliance
|
||||
* with the License. You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing,
|
||||
* software distributed under the License is distributed on an
|
||||
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
||||
* KIND, either express or implied. See the License for the
|
||||
* specific language governing permissions and limitations
|
||||
* under the License.
|
||||
* ====================================================================
|
||||
*
|
||||
* This software consists of voluntary contributions made by many
|
||||
* individuals on behalf of the Apache Software Foundation. For more
|
||||
* information on the Apache Software Foundation, please see
|
||||
* <http://www.apache.org/>.
|
||||
*
|
||||
*/
|
||||
-->
|
||||
</head>
|
||||
<body>
|
||||
The implementation of a thread-safe client connection manager.
|
||||
|
||||
<center>
|
||||
<image src="doc-files/tsccm-structure.png" alt="Relation Diagram"/>
|
||||
</center>
|
||||
|
||||
<p>
|
||||
The implementation is structured into three areas, as illustrated
|
||||
by the diagram above.
|
||||
Facing the application is the <i>Manager</i> (green), which internally
|
||||
maintains a <i>Pool</i> (yellow) of connections and waiting threads.
|
||||
Both Manager and Pool rely on <i>Operations</i> (cyan) to provide the
|
||||
actual connections.
|
||||
</p>
|
||||
</p>
|
||||
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:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Applications reference only the Manager objects.</li>
|
||||
<li>Manager objects reference Pool objects, but not vice versa.</li>
|
||||
<li>Operations objects do not reference either Manager or Pool objects.</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
The following table shows a selection of classes and interfaces,
|
||||
and their assignment to the three areas.
|
||||
</p>
|
||||
<center>
|
||||
<table border="1">
|
||||
<colgroup>
|
||||
<col width="50%"/>
|
||||
<col width="50%"/>
|
||||
</colgroup>
|
||||
|
||||
<tr>
|
||||
<td style="text-align: center; background-color: #00ff00;">
|
||||
{@link org.apache.http.impl.conn.tsccm.ThreadSafeClientConnManager}
|
||||
</td>
|
||||
<td style="text-align: center; background-color: #ffff00;">
|
||||
{@link org.apache.http.impl.conn.tsccm.AbstractConnPool}
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td style="text-align: center; background-color: #00ff00;">
|
||||
{@link org.apache.http.impl.conn.tsccm.TSCCMConnAdapter}
|
||||
</td>
|
||||
<td style="text-align: center; background-color: #ffff00;">
|
||||
{@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute}
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<!-- appears on both sides! -->
|
||||
|
||||
<tr>
|
||||
<td style="text-align: right; background-color: #00ff00;">
|
||||
{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
|
||||
</td>
|
||||
<td style="text-align: left; background-color: #ffff00;">
|
||||
{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<!-- ====================== -->
|
||||
|
||||
<tr style="border-width: 5px;">
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td colspan="2" style="text-align: center; background-color: #00ffff;">
|
||||
{@link org.apache.http.conn.ClientConnectionOperator}
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td colspan="2" style="text-align: center; background-color: #00ffff;">
|
||||
{@link org.apache.http.conn.OperatedClientConnection}
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
</center>
|
||||
|
||||
<p>
|
||||
The Manager area has implementations for the connection management
|
||||
interfaces {@link org.apache.http.conn.ClientConnectionManager}
|
||||
and {@link org.apache.http.conn.ManagedClientConnection}.
|
||||
The latter is an adapter from managed to operated connections, based on a
|
||||
{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}.
|
||||
<br/>
|
||||
The Pool area shows an abstract pool class
|
||||
{@link org.apache.http.impl.conn.tsccm.AbstractConnPool}
|
||||
and a concrete implementation
|
||||
{@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute}
|
||||
which uses the same basic algorithm as the
|
||||
<code>MultiThreadedHttpConnectionManager</code>
|
||||
in HttpClient 3.x.
|
||||
A pool contains instances of
|
||||
{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}.
|
||||
Most other classes in this package also belong to the Pool area.
|
||||
<br/>
|
||||
In the Operations area, you will find only the interfaces for
|
||||
operated connections as defined in {@link org.apache.http.conn}.
|
||||
The connection manager will work with all correct implementations
|
||||
of these interfaces. This package therefore does not define anything
|
||||
specific to the Operations area.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
As you have surely noticed, the
|
||||
{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
|
||||
appears in both the Manager and Pool areas.
|
||||
This is where things get tricky for connection garbage collection.
|
||||
<br/>
|
||||
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.
|
||||
<br/>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
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.
|
||||
<br/>
|
||||
In order to detect garbage collection of pool entries handed out
|
||||
to the application, the pool keeps a <i>weak reference</i> to the
|
||||
entry. Instances of
|
||||
{@link org.apache.http.impl.conn.tsccm.BasicPoolEntryRef}
|
||||
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 {@link
|
||||
org.apache.http.conn.ClientConnectionManager#closeIdleConnections cleanup}
|
||||
method of the connection manager.
|
||||
<br/>
|
||||
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.
|
||||
</p>
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Reference in New Issue