/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

  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>
  33. The implementation of a thread-safe client connection manager.
  34. <center>
  35. <img src="doc-files/tsccm-structure.png" alt="Relation Diagram"/>
  36. </center>
  37. <p>
  38. The implementation is structured into three areas, as illustrated
  39. by the diagram above.
  40. Facing the application is the <i>Manager</i> (green), which internally
  41. maintains a <i>Pool</i> (yellow) of connections and waiting threads.
  42. Both Manager and Pool rely on <i>Operations</i> (cyan) to provide the
  43. actual connections.
  44. </p>
  45. <p>
  46. In order to allow connection garbage collection, it is
  47. imperative that hard object references between the areas are
  48. restricted to the relations indicated by arrows in the diagram:
  49. </p>
  50. <ul>
  51. <li>Applications reference only the Manager objects.</li>
  52. <li>Manager objects reference Pool objects, but not vice versa.</li>
  53. <li>Operations objects do not reference either Manager or Pool objects.</li>
  54. </ul>
  55. <p>
  56. The following table shows a selection of classes and interfaces,
  57. and their assignment to the three areas.
  58. </p>
  59. <center>
  60. <table border="1">
  61. <colgroup>
  62. <col width="50%"/>
  63. <col width="50%"/>
  64. </colgroup>
  65. <tr>
  66. <td style="text-align: center; background-color: #00ff00;">
  67. {@link org.apache.http.impl.conn.tsccm.ThreadSafeClientConnManager}
  68. </td>
  69. <td style="text-align: center; background-color: #ffff00;">
  70. {@link org.apache.http.impl.conn.tsccm.AbstractConnPool}
  71. </td>
  72. </tr>
  73. <tr>
  74. <td style="text-align: center; background-color: #00ff00;">
  75. {@link org.apache.http.impl.conn.tsccm.BasicPooledConnAdapter}
  76. </td>
  77. <td style="text-align: center; background-color: #ffff00;">
  78. {@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute}
  79. </td>
  80. </tr>
  81. <!-- appears on both sides! -->
  82. <tr>
  83. <td style="text-align: right; background-color: #00ff00;">
  84. {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
  85. </td>
  86. <td style="text-align: left; background-color: #ffff00;">
  87. {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
  88. </td>
  89. </tr>
  90. <!-- ====================== -->
  91. <tr style="border-width: 5px;">
  92. </tr>
  93. <tr>
  94. <td colspan="2" style="text-align: center; background-color: #00ffff;">
  95. {@link org.apache.http.conn.ClientConnectionOperator}
  96. </td>
  97. </tr>
  98. <tr>
  99. <td colspan="2" style="text-align: center; background-color: #00ffff;">
  100. {@link org.apache.http.conn.OperatedClientConnection}
  101. </td>
  102. </tr>
  103. </table>
  104. </center>
  105. <p>
  106. The Manager area has implementations for the connection management
  107. interfaces {@link org.apache.http.conn.ClientConnectionManager}
  108. and {@link org.apache.http.conn.ManagedClientConnection}.
  109. The latter is an adapter from managed to operated connections, based on a
  110. {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}.
  111. <br/>
  112. The Pool area shows an abstract pool class
  113. {@link org.apache.http.impl.conn.tsccm.AbstractConnPool}
  114. and a concrete implementation
  115. {@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute}
  116. which uses the same basic algorithm as the
  117. <code>MultiThreadedHttpConnectionManager</code>
  118. in HttpClient 3.x.
  119. A pool contains instances of
  120. {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}.
  121. Most other classes in this package also belong to the Pool area.
  122. <br/>
  123. In the Operations area, you will find only the interfaces for
  124. operated connections as defined in the org.apache.http.conn package.
  125. The connection manager will work with all correct implementations
  126. of these interfaces. This package therefore does not define anything
  127. specific to the Operations area.
  128. </p>
  129. <p>
  130. As you have surely noticed, the
  131. {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
  132. appears in both the Manager and Pool areas.
  133. This is where things get tricky for connection garbage collection.
  134. <br/>
  135. A connection pool may start a background thread to implement cleanup.
  136. In that case, the connection pool will not be garbage collected until
  137. it is shut down, since the background thread keeps a hard reference
  138. to the pool. The pool itself keeps hard references to the pooled entries,
  139. which in turn reference idle connections. Neither of these is subject
  140. to garbage collection.
  141. Only the shutdown of the pool will stop the background thread,
  142. thereby enabling garbage collection of the pool objects.
  143. <br/>
  144. A pool entry that is passed to an application by means of a connection
  145. adapter will move from the Pool area to the Manager area. When the
  146. connection is released by the application, the manager returns the
  147. entry back to the pool. With that step, the pool entry moves from
  148. the Manager area back to the Pool area.
  149. While the entry is in the Manager area, the pool MUST NOT keep a
  150. hard reference to it.
  151. </p>
  152. <p>
  153. The purpose of connection garbage collection is to detect when an
  154. application fails to return a connection. In order to achieve this,
  155. the only hard reference to the pool entry in the Manager area is
  156. in the connection wrapper. The manager will not keep a hard reference
  157. to the connection wrapper either, since that wrapper is effectively
  158. moving to the Application area.
  159. If the application drops it's reference to the connection wrapper,
  160. that wrapper will be garbage collected, and with it the pool entry.
  161. <br/>
  162. In order to detect garbage collection of pool entries handed out
  163. to the application, the pool keeps a <i>weak reference</i> to the
  164. entry. Instances of
  165. {@link org.apache.http.impl.conn.tsccm.BasicPoolEntryRef}
  166. combine the weak reference with information about the route for
  167. which the pool entry was allocated. If one of these entry references
  168. becomes stale, the pool can accommodate for the lost connection.
  169. This is triggered either by a background thread waiting for the
  170. references to be queued by the garbage collector, or by the
  171. application calling a {@link
  172. org.apache.http.conn.ClientConnectionManager#closeIdleConnections cleanup}
  173. method of the connection manager.
  174. <br/>
  175. Basically the same trick is used for detecting garbage collection
  176. of the connection manager itself. The pool keeps a weak reference
  177. to the connection manager that created it. However, this will work
  178. only if there is a background thread to detect when that reference
  179. is queued by the garbage collector. Otherwise, a finalizer of the
  180. connection manager will shut down the pool and release it's resources.
  181. </p>
  182. </body>
  183. </html>