From 532fddb7aa87bbb7bac18fe671354a70248443aa Mon Sep 17 00:00:00 2001 From: Roland Weber Date: Sat, 11 Aug 2007 18:02:18 +0000 Subject: [PATCH] TSCCM package JavaDocs git-svn-id: https://svn.apache.org/repos/asf/jakarta/httpcomponents/httpclient/trunk@564950 13f79535-47bb-0310-9956-ffa450edef68 --- .../conn/tsccm/doc-files/tsccm-structure.png | Bin 0 -> 4224 bytes .../apache/http/impl/conn/tsccm/package.html | 204 ++++++++++++++++++ 2 files changed, 204 insertions(+) create mode 100644 module-client/src/main/java/org/apache/http/impl/conn/tsccm/doc-files/tsccm-structure.png create mode 100644 module-client/src/main/java/org/apache/http/impl/conn/tsccm/package.html diff --git a/module-client/src/main/java/org/apache/http/impl/conn/tsccm/doc-files/tsccm-structure.png b/module-client/src/main/java/org/apache/http/impl/conn/tsccm/doc-files/tsccm-structure.png new file mode 100644 index 0000000000000000000000000000000000000000..2e2820db4c4253194e46421096738eb1989a8fe9 GIT binary patch literal 4224 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 literal 0 HcmV?d00001 diff --git a/module-client/src/main/java/org/apache/http/impl/conn/tsccm/package.html b/module-client/src/main/java/org/apache/http/impl/conn/tsccm/package.html new file mode 100644 index 000000000..0b12ac982 --- /dev/null +++ b/module-client/src/main/java/org/apache/http/impl/conn/tsccm/package.html @@ -0,0 +1,204 @@ + + + + + +The implementation of a thread-safe client connection manager. + +
+Relation Diagram +
+ +

+The implementation is structured into three areas, as illustrated +by the diagram above. +Facing the application is the Manager (green), which internally +maintains a Pool (yellow) of connections and waiting threads. +Both Manager and Pool rely on Operations (cyan) to provide the +actual connections. +

+

+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: +

+
    +
  • Applications reference only the Manager objects.
    • +
  • Manager objects reference Pool objects, but not vice versa.
    • +
  • Operations objects do not reference either Manager or Pool objects.
    • +
+ +

+The following table shows a selection of classes and interfaces, +and their assignment to the three areas. +

+
+ ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+{@link org.apache.http.impl.conn.tsccm.ThreadSafeClientConnManager} + +{@link org.apache.http.impl.conn.tsccm.AbstractConnPool} +
+{@link org.apache.http.impl.conn.tsccm.TSCCMConnAdapter} + +{@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute} +
+{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry} + +{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry} +
+{@link org.apache.http.conn.ClientConnectionOperator} +
+{@link org.apache.http.conn.OperatedClientConnection} +
+
+ +

+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}. +
+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 +MultiThreadedHttpConnectionManager +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. +
+In the Operations area, you will find only the interfaces for +operated connections as defined in {@link org.apache.http.conn}. +The connection manager will work with all correct implementations +of these interfaces. This package therefore does not define anything +specific to the Operations area. +

+ +

+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. +
+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. +
+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. +

+ +

+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. +
+In order to detect garbage collection of pool entries handed out +to the application, the pool keeps a weak reference 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. +
+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. +

+ + + +