svn commit: r1147958 - in /httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client: AIMDBackoffManager.java Clock.java SystemClock.java

[jo...@apache.org]

Author: jonm
Date: Mon Jul 18 16:31:28 2011
New Revision: 1147958

URL: http://svn.apache.org/viewvc?rev=1147958&view=rev
Log:
HTTPCLIENT-1101: make Clock and SystemClock package-private, since they
are only used to expose hooks for unit testing time-related behaviors,
and we don't want them as part of the public API. Also expanded the
Javadoc for the AIMDBackoffManager.

Modified:
    httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/AIMDBackoffManager.java
    httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/Clock.java
    httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/SystemClock.java

Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/AIMDBackoffManager.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/AIMDBackoffManager.java?rev=1147958&r1=1147957&r2=1147958&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/AIMDBackoffManager.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/AIMDBackoffManager.java Mon Jul 18 16:31:28 2011
@@ -8,9 +8,22 @@ import org.apache.http.conn.params.ConnP
 import org.apache.http.conn.routing.HttpRoute;
 
 /**
- * The <code>AIMDBackoffManager</code> applies an additive increase,
+ * <p>The <code>AIMDBackoffManager</code> applies an additive increase,
  * multiplicative decrease (AIMD) to managing a dynamic limit to
- * the number of connections allowed to a given host.
+ * the number of connections allowed to a given host. You may want
+ * to experiment with the settings for the cooldown periods and the
+ * backoff factor to get the adaptive behavior you want.</p>
+ * 
+ * <p>Generally speaking, shorter cooldowns will lead to more steady-state
+ * variability but faster reaction times, while longer cooldowns
+ * will lead to more stable equilibrium behavior but slower reaction
+ * times.</p>
+ * 
+ * <p>Similarly, higher backoff factors promote greater
+ * utilization of available capacity at the expense of fairness
+ * among clients. Lower backoff factors allow equal distribution of
+ * capacity among clients (fairness) to happen faster, at the
+ * expense of having more server capacity unused in the short term.</p>
  * 
  * @since 4.2
  */
@@ -81,7 +94,7 @@ public class AIMDBackoffManager implemen
 
     /**
      * Sets the factor to use when backing off; the new
-     * per-host limit will be roughly, the current max times
+     * per-host limit will be roughly the current max times
      * this factor. <code>Math.floor</code> is applied in the
      * case of non-integer outcomes to ensure we actually
      * decrease the pool size. Pool sizes are never decreased

Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/Clock.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/Clock.java?rev=1147958&r1=1147957&r2=1147958&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/Clock.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/Clock.java Mon Jul 18 16:31:28 2011
@@ -6,7 +6,7 @@ package org.apache.http.impl.client;
  * @since 4.2
  *
  */
-public interface Clock {
+interface Clock {
 
     /**
      * Returns the current time, expressed as the number of

Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/SystemClock.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/SystemClock.java?rev=1147958&r1=1147957&r2=1147958&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/SystemClock.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/SystemClock.java Mon Jul 18 16:31:28 2011
@@ -5,7 +5,7 @@ package org.apache.http.impl.client;
  * 
  * @since 4.2
  */
-public class SystemClock implements Clock {
+class SystemClock implements Clock {
 
     public long getCurrentTime() {
         return System.currentTimeMillis();