| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!--NewPage--> |
| <HTML> |
| <HEAD> |
| <!-- Generated by javadoc (build 1.5.0_22) on Sun Oct 21 11:03:15 GMT+01:00 2012 --> |
| <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <TITLE> |
| org.apache.http.impl.conn.tsccm (HttpComponents Client 4.2.2 API) |
| </TITLE> |
| |
| <META NAME="keywords" CONTENT="org.apache.http.impl.conn.tsccm package"> |
| |
| <LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../../../stylesheet.css" TITLE="Style"> |
| |
| <SCRIPT type="text/javascript"> |
| function windowTitle() |
| { |
| parent.document.title="org.apache.http.impl.conn.tsccm (HttpComponents Client 4.2.2 API)"; |
| } |
| </SCRIPT> |
| <NOSCRIPT> |
| </NOSCRIPT> |
| |
| </HEAD> |
| |
| <BODY BGCOLOR="white" onload="windowTitle();"> |
| |
| |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <A NAME="navbar_top"><!-- --></A> |
| <A HREF="#skip-navbar_top" title="Skip navigation links"></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> |
| <TR> |
| <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> |
| <A NAME="navbar_top_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> |
| <TR ALIGN="center" VALIGN="top"> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> |
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> |
| </TR> |
| </TABLE> |
| </TD> |
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> |
| </EM> |
| </TD> |
| </TR> |
| |
| <TR> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../../../../../org/apache/http/impl/conn/package-summary.html"><B>PREV PACKAGE</B></A> |
| <A HREF="../../../../../../org/apache/http/impl/cookie/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../../../../../index.html?org/apache/http/impl/conn/tsccm/package-summary.html" target="_top"><B>FRAMES</B></A> |
| <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> |
| <SCRIPT type="text/javascript"> |
| <!-- |
| if(window==top) { |
| document.writeln('<A HREF="../../../../../../allclasses-noframe.html"><B>All Classes</B></A>'); |
| } |
| //--> |
| </SCRIPT> |
| <NOSCRIPT> |
| <A HREF="../../../../../../allclasses-noframe.html"><B>All Classes</B></A> |
| </NOSCRIPT> |
| |
| |
| </FONT></TD> |
| </TR> |
| </TABLE> |
| <A NAME="skip-navbar_top"></A> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| |
| <HR> |
| <H2> |
| Package org.apache.http.impl.conn.tsccm |
| </H2> |
| The implementation of a thread-safe client connection manager. |
| <P> |
| <B>See:</B> |
| <BR> |
| <A HREF="#package_description"><B>Description</B></A> |
| <P> |
| |
| <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> |
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> |
| <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> |
| <B>Interface Summary</B></FONT></TH> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/http/impl/conn/tsccm/PoolEntryRequest.html" title="interface in org.apache.http.impl.conn.tsccm">PoolEntryRequest</A></B></TD> |
| <TD><B>Deprecated.</B> <I>(4.2) use <A HREF="http://download.oracle.com/javase/1.5.0/docs/api/java/util/concurrent/Future.html" title="class or interface in java.util.concurrent"><CODE>Future</CODE></A></I></TD> |
| </TR> |
| </TABLE> |
| |
| |
| <P> |
| |
| <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> |
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> |
| <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> |
| <B>Class Summary</B></FONT></TH> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/http/impl/conn/tsccm/AbstractConnPool.html" title="class in org.apache.http.impl.conn.tsccm">AbstractConnPool</A></B></TD> |
| <TD><B>Deprecated.</B> <I>(4.2) use <A HREF="http://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/pool/AbstractConnPool.html" title="class or interface in org.apache.http.pool"><CODE>AbstractConnPool</CODE></A></I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/http/impl/conn/tsccm/BasicPooledConnAdapter.html" title="class in org.apache.http.impl.conn.tsccm">BasicPooledConnAdapter</A></B></TD> |
| <TD><B>Deprecated.</B> <I>(4.2) do not use</I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/http/impl/conn/tsccm/BasicPoolEntry.html" title="class in org.apache.http.impl.conn.tsccm">BasicPoolEntry</A></B></TD> |
| <TD><B>Deprecated.</B> <I>(4.2) use <A HREF="http://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/pool/PoolEntry.html" title="class or interface in org.apache.http.pool"><CODE>PoolEntry</CODE></A></I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/http/impl/conn/tsccm/BasicPoolEntryRef.html" title="class in org.apache.http.impl.conn.tsccm">BasicPoolEntryRef</A></B></TD> |
| <TD><B>Deprecated.</B> <I>(4.2) do not use</I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/http/impl/conn/tsccm/ConnPoolByRoute.html" title="class in org.apache.http.impl.conn.tsccm">ConnPoolByRoute</A></B></TD> |
| <TD><B>Deprecated.</B> <I>(4.2) use <A HREF="http://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/pool/AbstractConnPool.html" title="class or interface in org.apache.http.pool"><CODE>AbstractConnPool</CODE></A></I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/http/impl/conn/tsccm/RouteSpecificPool.html" title="class in org.apache.http.impl.conn.tsccm">RouteSpecificPool</A></B></TD> |
| <TD><B>Deprecated.</B> <I>(4.2) use <A HREF="http://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/pool/AbstractConnPool.html" title="class or interface in org.apache.http.pool"><CODE>AbstractConnPool</CODE></A></I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/http/impl/conn/tsccm/ThreadSafeClientConnManager.html" title="class in org.apache.http.impl.conn.tsccm">ThreadSafeClientConnManager</A></B></TD> |
| <TD><B>Deprecated.</B> <I>(4.2) use <A HREF="../../../../../../org/apache/http/impl/conn/PoolingClientConnectionManager.html" title="class in org.apache.http.impl.conn"><CODE>PoolingClientConnectionManager</CODE></A></I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/http/impl/conn/tsccm/WaitingThread.html" title="class in org.apache.http.impl.conn.tsccm">WaitingThread</A></B></TD> |
| <TD><B>Deprecated.</B> <I>(4.2) do not use</I></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/http/impl/conn/tsccm/WaitingThreadAborter.html" title="class in org.apache.http.impl.conn.tsccm">WaitingThreadAborter</A></B></TD> |
| <TD><B>Deprecated.</B> <I>(4.2) do not use</I></TD> |
| </TR> |
| </TABLE> |
| |
| |
| <P> |
| <A NAME="package_description"><!-- --></A><H2> |
| Package org.apache.http.impl.conn.tsccm Description |
| </H2> |
| |
| <P> |
| 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;"> |
| <A HREF="../../../../../../org/apache/http/impl/conn/tsccm/ThreadSafeClientConnManager.html" title="class in org.apache.http.impl.conn.tsccm"><CODE>ThreadSafeClientConnManager</CODE></A> |
| </td> |
| <td style="text-align: center; background-color: #ffff00;"> |
| <A HREF="../../../../../../org/apache/http/impl/conn/tsccm/AbstractConnPool.html" title="class in org.apache.http.impl.conn.tsccm"><CODE>AbstractConnPool</CODE></A> |
| </td> |
| </tr> |
| |
| <tr> |
| <td style="text-align: center; background-color: #00ff00;"> |
| <A HREF="../../../../../../org/apache/http/impl/conn/tsccm/BasicPooledConnAdapter.html" title="class in org.apache.http.impl.conn.tsccm"><CODE>BasicPooledConnAdapter</CODE></A> |
| </td> |
| <td style="text-align: center; background-color: #ffff00;"> |
| <A HREF="../../../../../../org/apache/http/impl/conn/tsccm/ConnPoolByRoute.html" title="class in org.apache.http.impl.conn.tsccm"><CODE>ConnPoolByRoute</CODE></A> |
| </td> |
| </tr> |
| |
| <!-- appears on both sides! --> |
| |
| <tr> |
| <td style="text-align: right; background-color: #00ff00;"> |
| <A HREF="../../../../../../org/apache/http/impl/conn/tsccm/BasicPoolEntry.html" title="class in org.apache.http.impl.conn.tsccm"><CODE>BasicPoolEntry</CODE></A> |
| </td> |
| <td style="text-align: left; background-color: #ffff00;"> |
| <A HREF="../../../../../../org/apache/http/impl/conn/tsccm/BasicPoolEntry.html" title="class in org.apache.http.impl.conn.tsccm"><CODE>BasicPoolEntry</CODE></A> |
| </td> |
| </tr> |
| |
| <!-- ====================== --> |
| |
| <tr style="border-width: 5px;"> |
| </tr> |
| |
| <tr> |
| <td colspan="2" style="text-align: center; background-color: #00ffff;"> |
| <A HREF="../../../../../../org/apache/http/conn/ClientConnectionOperator.html" title="interface in org.apache.http.conn"><CODE>ClientConnectionOperator</CODE></A> |
| </td> |
| </tr> |
| |
| <tr> |
| <td colspan="2" style="text-align: center; background-color: #00ffff;"> |
| <A HREF="../../../../../../org/apache/http/conn/OperatedClientConnection.html" title="interface in org.apache.http.conn"><CODE>OperatedClientConnection</CODE></A> |
| </td> |
| </tr> |
| |
| </table> |
| </center> |
| |
| <p> |
| The Manager area has implementations for the connection management |
| interfaces <A HREF="../../../../../../org/apache/http/conn/ClientConnectionManager.html" title="interface in org.apache.http.conn"><CODE>ClientConnectionManager</CODE></A> |
| and <A HREF="../../../../../../org/apache/http/conn/ManagedClientConnection.html" title="interface in org.apache.http.conn"><CODE>ManagedClientConnection</CODE></A>. |
| The latter is an adapter from managed to operated connections, based on a |
| <A HREF="../../../../../../org/apache/http/impl/conn/tsccm/BasicPoolEntry.html" title="class in org.apache.http.impl.conn.tsccm"><CODE>BasicPoolEntry</CODE></A>. |
| <br/> |
| The Pool area shows an abstract pool class |
| <A HREF="../../../../../../org/apache/http/impl/conn/tsccm/AbstractConnPool.html" title="class in org.apache.http.impl.conn.tsccm"><CODE>AbstractConnPool</CODE></A> |
| and a concrete implementation |
| <A HREF="../../../../../../org/apache/http/impl/conn/tsccm/ConnPoolByRoute.html" title="class in org.apache.http.impl.conn.tsccm"><CODE>ConnPoolByRoute</CODE></A> |
| which uses the same basic algorithm as the |
| <code>MultiThreadedHttpConnectionManager</code> |
| in HttpClient 3.x. |
| A pool contains instances of |
| <A HREF="../../../../../../org/apache/http/impl/conn/tsccm/BasicPoolEntry.html" title="class in org.apache.http.impl.conn.tsccm"><CODE>BasicPoolEntry</CODE></A>. |
| 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 |
| <A HREF="../../../../../../org/apache/http/impl/conn/tsccm/BasicPoolEntry.html" title="class in org.apache.http.impl.conn.tsccm"><CODE>BasicPoolEntry</CODE></A> |
| 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 |
| <A HREF="../../../../../../org/apache/http/impl/conn/tsccm/BasicPoolEntryRef.html" title="class in org.apache.http.impl.conn.tsccm"><CODE>BasicPoolEntryRef</CODE></A> |
| 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 <A HREF="../../../../../../org/apache/http/conn/ClientConnectionManager.html#closeIdleConnections(long, java.util.concurrent.TimeUnit)"><CODE>cleanup</CODE></A> |
| 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> |
| <P> |
| |
| <P> |
| <DL> |
| </DL> |
| <HR> |
| |
| |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <A NAME="navbar_bottom"><!-- --></A> |
| <A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> |
| <TR> |
| <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> |
| <A NAME="navbar_bottom_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> |
| <TR ALIGN="center" VALIGN="top"> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> |
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> |
| </TR> |
| </TABLE> |
| </TD> |
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> |
| </EM> |
| </TD> |
| </TR> |
| |
| <TR> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../../../../../org/apache/http/impl/conn/package-summary.html"><B>PREV PACKAGE</B></A> |
| <A HREF="../../../../../../org/apache/http/impl/cookie/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../../../../../index.html?org/apache/http/impl/conn/tsccm/package-summary.html" target="_top"><B>FRAMES</B></A> |
| <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> |
| <SCRIPT type="text/javascript"> |
| <!-- |
| if(window==top) { |
| document.writeln('<A HREF="../../../../../../allclasses-noframe.html"><B>All Classes</B></A>'); |
| } |
| //--> |
| </SCRIPT> |
| <NOSCRIPT> |
| <A HREF="../../../../../../allclasses-noframe.html"><B>All Classes</B></A> |
| </NOSCRIPT> |
| |
| |
| </FONT></TD> |
| </TR> |
| </TABLE> |
| <A NAME="skip-navbar_bottom"></A> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| |
| <HR> |
| Copyright © 1999-2012 <a href="http://www.apache.org/">The Apache Software Foundation</a>. All Rights Reserved. |
| </BODY> |
| </HTML> |
