/lib/src/org/apache/http/impl/conn/tsccm/package.html
http://github.com/onedanshow/Screen-Courter · HTML · 200 lines · 153 code · 17 blank · 30 comment · 0 complexity · 99e50c3bfaeda315182d7108e49bf45b MD5 · raw file
- <html>
- <head>
- <!--
- /*
- * ====================================================================
- * 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>
- <img 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.BasicPooledConnAdapter}
- </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 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.
- </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>