1 <html> 2 <head> 3 <!-- 4 /* 5 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/impl/conn/tsccm/package.html $ 6 * $Revision: 653041 $ 7 * $Date: 2008-05-03 03:39:28 -0700 (Sat, 03 May 2008) $ 8 * 9 * ==================================================================== 10 * Licensed to the Apache Software Foundation (ASF) under one 11 * or more contributor license agreements. See the NOTICE file 12 * distributed with this work for additional information 13 * regarding copyright ownership. The ASF licenses this file 14 * to you under the Apache License, Version 2.0 (the 15 * "License"); you may not use this file except in compliance 16 * with the License. You may obtain a copy of the License at 17 * 18 * http://www.apache.org/licenses/LICENSE-2.0 19 * 20 * Unless required by applicable law or agreed to in writing, 21 * software distributed under the License is distributed on an 22 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 23 * KIND, either express or implied. See the License for the 24 * specific language governing permissions and limitations 25 * under the License. 26 * ==================================================================== 27 * 28 * This software consists of voluntary contributions made by many 29 * individuals on behalf of the Apache Software Foundation. For more 30 * information on the Apache Software Foundation, please see 31 * <http://www.apache.org/>. 32 * 33 */ 34 --> 35 </head> 36 <body> 37 38 The implementation of a thread-safe client connection manager. 39 40 <center> 41 <img src="doc-files/tsccm-structure.png" alt="Relation Diagram"/> 42 </center> 43 44 <p> 45 The implementation is structured into three areas, as illustrated 46 by the diagram above. 47 Facing the application is the <i>Manager</i> (green), which internally 48 maintains a <i>Pool</i> (yellow) of connections and waiting threads. 49 Both Manager and Pool rely on <i>Operations</i> (cyan) to provide the 50 actual connections. 51 </p> 52 <p> 53 In order to allow connection garbage collection, it is 54 imperative that hard object references between the areas are 55 restricted to the relations indicated by arrows in the diagram: 56 </p> 57 <ul> 58 <li>Applications reference only the Manager objects.</li> 59 <li>Manager objects reference Pool objects, but not vice versa.</li> 60 <li>Operations objects do not reference either Manager or Pool objects.</li> 61 </ul> 62 63 <p> 64 The following table shows a selection of classes and interfaces, 65 and their assignment to the three areas. 66 </p> 67 <center> 68 <table border="1"> 69 <colgroup> 70 <col width="50%"/> 71 <col width="50%"/> 72 </colgroup> 73 74 <tr> 75 <td style="text-align: center; background-color: #00ff00;"> 76 {@link org.apache.http.impl.conn.tsccm.ThreadSafeClientConnManager} 77 </td> 78 <td style="text-align: center; background-color: #ffff00;"> 79 {@link org.apache.http.impl.conn.tsccm.AbstractConnPool} 80 </td> 81 </tr> 82 83 <tr> 84 <td style="text-align: center; background-color: #00ff00;"> 85 {@link org.apache.http.impl.conn.tsccm.BasicPooledConnAdapter} 86 </td> 87 <td style="text-align: center; background-color: #ffff00;"> 88 {@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute} 89 </td> 90 </tr> 91 92 <!-- appears on both sides! --> 93 94 <tr> 95 <td style="text-align: right; background-color: #00ff00;"> 96 {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry} 97 </td> 98 <td style="text-align: left; background-color: #ffff00;"> 99 {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry} 100 </td> 101 </tr> 102 103 <!-- ====================== --> 104 105 <tr style="border-width: 5px;"> 106 </tr> 107 108 <tr> 109 <td colspan="2" style="text-align: center; background-color: #00ffff;"> 110 {@link org.apache.http.conn.ClientConnectionOperator} 111 </td> 112 </tr> 113 114 <tr> 115 <td colspan="2" style="text-align: center; background-color: #00ffff;"> 116 {@link org.apache.http.conn.OperatedClientConnection} 117 </td> 118 </tr> 119 120 </table> 121 </center> 122 123 <p> 124 The Manager area has implementations for the connection management 125 interfaces {@link org.apache.http.conn.ClientConnectionManager} 126 and {@link org.apache.http.conn.ManagedClientConnection}. 127 The latter is an adapter from managed to operated connections, based on a 128 {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}. 129 <br/> 130 The Pool area shows an abstract pool class 131 {@link org.apache.http.impl.conn.tsccm.AbstractConnPool} 132 and a concrete implementation 133 {@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute} 134 which uses the same basic algorithm as the 135 <code>MultiThreadedHttpConnectionManager</code> 136 in HttpClient 3.x. 137 A pool contains instances of 138 {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}. 139 Most other classes in this package also belong to the Pool area. 140 <br/> 141 In the Operations area, you will find only the interfaces for 142 operated connections as defined in the org.apache.http.conn package. 143 The connection manager will work with all correct implementations 144 of these interfaces. This package therefore does not define anything 145 specific to the Operations area. 146 </p> 147 148 <p> 149 As you have surely noticed, the 150 {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry} 151 appears in both the Manager and Pool areas. 152 This is where things get tricky for connection garbage collection. 153 <br/> 154 A connection pool may start a background thread to implement cleanup. 155 In that case, the connection pool will not be garbage collected until 156 it is shut down, since the background thread keeps a hard reference 157 to the pool. The pool itself keeps hard references to the pooled entries, 158 which in turn reference idle connections. Neither of these is subject 159 to garbage collection. 160 Only the shutdown of the pool will stop the background thread, 161 thereby enabling garbage collection of the pool objects. 162 <br/> 163 A pool entry that is passed to an application by means of a connection 164 adapter will move from the Pool area to the Manager area. When the 165 connection is released by the application, the manager returns the 166 entry back to the pool. With that step, the pool entry moves from 167 the Manager area back to the Pool area. 168 While the entry is in the Manager area, the pool MUST NOT keep a 169 hard reference to it. 170 </p> 171 172 <p> 173 The purpose of connection garbage collection is to detect when an 174 application fails to return a connection. In order to achieve this, 175 the only hard reference to the pool entry in the Manager area is 176 in the connection wrapper. The manager will not keep a hard reference 177 to the connection wrapper either, since that wrapper is effectively 178 moving to the Application area. 179 If the application drops it's reference to the connection wrapper, 180 that wrapper will be garbage collected, and with it the pool entry. 181 <br/> 182 In order to detect garbage collection of pool entries handed out 183 to the application, the pool keeps a <i>weak reference</i> to the 184 entry. Instances of 185 {@link org.apache.http.impl.conn.tsccm.BasicPoolEntryRef} 186 combine the weak reference with information about the route for 187 which the pool entry was allocated. If one of these entry references 188 becomes stale, the pool can accommodate for the lost connection. 189 This is triggered either by a background thread waiting for the 190 references to be queued by the garbage collector, or by the 191 application calling a {@link 192 org.apache.http.conn.ClientConnectionManager#closeIdleConnections cleanup} 193 method of the connection manager. 194 <br/> 195 Basically the same trick is used for detecting garbage collection 196 of the connection manager itself. The pool keeps a weak reference 197 to the connection manager that created it. However, this will work 198 only if there is a background thread to detect when that reference 199 is queued by the garbage collector. Otherwise, a finalizer of the 200 connection manager will shut down the pool and release it's resources. 201 </p> 202 203 204 </body> 205 </html> 206
