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