Javadoc cleanups

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@767659 13f79535-47bb-0310-9956-ffa450edef68

httpclient/src/main/java/org/apache/http/conn/params/ConnConnectionPNames.java

@@ -30,17 +30,13 @@
 
 package org.apache.http.conn.params;
 
-
 /**
- * Parameter names for connections in HttpConn.
+ * Parameter names for HTTP client connections.
- *
- * @version $Revision$
  * 
  * @since 4.0
  */
 public interface ConnConnectionPNames {
 
-
     /**
      * Defines the maximum number of ignorable lines before we expect
      * a HTTP response's status line.

httpclient/src/main/java/org/apache/http/conn/params/ConnManagerPNames.java

@@ -30,11 +30,8 @@
 
 package org.apache.http.conn.params;
 
-
 /**
  * Parameter names for connection managers in HttpConn.
- *
- * @version $Revision$
  * 
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/conn/params/ConnManagerParams.java

@@ -40,9 +40,6 @@ import org.apache.http.params.HttpParams;
  * to client-side
  * {@link org.apache.http.conn.ClientConnectionManager connection managers}. 
  * 
- * 
- * @version $Revision$
- * 
  * @since 4.0
  *
  * @see ConnManagerPNames

httpclient/src/main/java/org/apache/http/conn/params/ConnPerRoute.java

@@ -34,13 +34,10 @@ import org.apache.http.conn.routing.HttpRoute;
 
 /**
  * This interface is intended for looking up maximum number of connections 
- * allowed for for a given route. This class can be used by pooling 
+ * allowed for a given route. This class can be used by pooling 
  * {@link org.apache.http.conn.ClientConnectionManager connection managers} for 
  * a fine-grained control of connections on a per route basis. 
  * 
- * 
- * @version $Revision$
- * 
  * @since 4.0
  */
 public interface ConnPerRoute {

httpclient/src/main/java/org/apache/http/conn/params/ConnPerRouteBean.java

@@ -43,9 +43,6 @@ import org.apache.http.conn.routing.HttpRoute;
  * {@link org.apache.http.conn.ClientConnectionManager connection managers} for 
  * a fine-grained control of connections on a per route basis. 
  * 
- * 
- * @version $Revision$
- * 
  * @since 4.0
  */
 @NotThreadSafe // maxPerHostMap and defaultMax
@@ -112,5 +109,10 @@ public final class ConnPerRouteBean implements ConnPerRoute {
         this.maxPerHostMap.clear();
         this.maxPerHostMap.putAll(map);
     }
+
+	@Override
+	public String toString() {
+		return this.maxPerHostMap.toString();
+	}
     
 }

httpclient/src/main/java/org/apache/http/conn/params/ConnRoutePNames.java

@@ -33,8 +33,6 @@ package org.apache.http.conn.params;
 /**
  * Parameter names for routing in HttpConn.
  * 
- * @version $Revision$
- * 
  * @since 4.0
  */
 public interface ConnRoutePNames {
@@ -50,7 +48,6 @@ public interface ConnRoutePNames {
      */
     public static final String DEFAULT_PROXY = "http.route.default-proxy";
 
-
     /**
      * Parameter for the local address.
      * On machines with multiple network interfaces, this parameter
@@ -65,7 +62,6 @@ public interface ConnRoutePNames {
      */
     public static final String LOCAL_ADDRESS = "http.route.local-address";
 
-
     /**
      * Parameter for an forced route.
      * The forced route will be interpreted by the standard

httpclient/src/main/java/org/apache/http/conn/params/ConnRouteParams.java

@@ -30,7 +30,6 @@
 
 package org.apache.http.conn.params;
 
-
 import java.net.InetAddress;
 
 import net.jcip.annotations.Immutable;
@@ -39,15 +38,10 @@ import org.apache.http.HttpHost;
 import org.apache.http.params.HttpParams;
 import org.apache.http.conn.routing.HttpRoute;
 
-
-
 /**
  * An adaptor for accessing route related parameters in {@link HttpParams}.
  * See {@link ConnRoutePNames} for parameter name definitions.
  * 
- * 
- * @version $Revision$
- * 
  * @since 4.0
  */
 @Immutable
@@ -67,13 +61,11 @@ public class ConnRouteParams implements ConnRoutePNames {
      */
     public static final HttpRoute NO_ROUTE = new HttpRoute(NO_HOST); // Immutable
 
-
     /** Disabled default constructor. */
     private ConnRouteParams() {
         // no body
     }
 
-
     /**
      * Obtains the {@link ConnRoutePNames#DEFAULT_PROXY DEFAULT_PROXY}
      * parameter value.
@@ -98,7 +90,6 @@ public class ConnRouteParams implements ConnRoutePNames {
         return proxy;
     }
 
-
     /**
      * Sets the {@link ConnRoutePNames#DEFAULT_PROXY DEFAULT_PROXY}
      * parameter value.
@@ -117,7 +108,6 @@ public class ConnRouteParams implements ConnRoutePNames {
         params.setParameter(DEFAULT_PROXY, proxy);
     }
 
-
     /**
      * Obtains the {@link ConnRoutePNames#FORCED_ROUTE FORCED_ROUTE}
      * parameter value.
@@ -142,7 +132,6 @@ public class ConnRouteParams implements ConnRoutePNames {
         return route;
     }
 
-
     /**
      * Sets the {@link ConnRoutePNames#FORCED_ROUTE FORCED_ROUTE}
      * parameter value.
@@ -161,7 +150,6 @@ public class ConnRouteParams implements ConnRoutePNames {
         params.setParameter(FORCED_ROUTE, route);
     }
 
-
     /**
      * Obtains the {@link ConnRoutePNames#LOCAL_ADDRESS LOCAL_ADDRESS}
      * parameter value.
@@ -184,7 +172,6 @@ public class ConnRouteParams implements ConnRoutePNames {
         return local;
     }
 
-
     /**
      * Sets the {@link ConnRoutePNames#LOCAL_ADDRESS LOCAL_ADDRESS}
      * parameter value.

httpclient/src/main/java/org/apache/http/impl/conn/DefaultClientConnection.java

@@ -56,9 +56,11 @@ import org.apache.http.conn.OperatedClientConnection;
  * The following parameters can be used to customize the behavior of this 
  * class: 
  * <ul>
+ *  <li>{@link org.apache.http.params.CoreProtocolPNames#STRICT_TRANSFER_ENCODING}</li>
  *  <li>{@link org.apache.http.params.CoreProtocolPNames#HTTP_ELEMENT_CHARSET}</li>
  *  <li>{@link org.apache.http.params.CoreConnectionPNames#SOCKET_BUFFER_SIZE}</li>
  *  <li>{@link org.apache.http.params.CoreConnectionPNames#MAX_LINE_LENGTH}</li>
+ *  <li>{@link org.apache.http.params.CoreConnectionPNames#MAX_HEADER_COUNT}</li>
  * </ul>
  *
  * @since 4.0
@@ -223,7 +225,10 @@ public class DefaultClientConnection extends SocketHttpClientConnection
 
     @Override
     public HttpResponse receiveResponseHeader() throws HttpException, IOException {
-        HttpResponse response = super.receiveResponseHeader();
+    	HttpResponse response = super.receiveResponseHeader();
+    	if (log.isDebugEnabled()) {
+            log.debug("Receiving response: " + response.getStatusLine());
+    	}
         if (headerLog.isDebugEnabled()) {
             headerLog.debug("<< " + response.getStatusLine().toString());
             Header[] headers = response.getAllHeaders();
@@ -236,6 +241,9 @@ public class DefaultClientConnection extends SocketHttpClientConnection
 
     @Override
     public void sendRequestHeader(HttpRequest request) throws HttpException, IOException {
+    	if (log.isDebugEnabled()) {
+            log.debug("Sending request: " + request.getRequestLine());
+    	}
         super.sendRequestHeader(request);
         if (headerLog.isDebugEnabled()) {
             headerLog.debug(">> " + request.getRequestLine().toString());

httpclient/src/main/java/org/apache/http/impl/conn/tsccm/ConnPoolByRoute.java

@@ -58,18 +58,17 @@ import org.apache.http.params.HttpParams;
  * <li>connections are re-used only for the exact same route</li>
  * <li>connection limits are enforced per route rather than per host</li>
  * </ul>
- * Note that access to the pool datastructures is synchronized via the
+ * Note that access to the pool data structures is synchronized via the
  * {@link AbstractConnPool#poolLock poolLock} in the base class,
  * not via <code>synchronized</code> methods.
  *
- *
  * @since 4.0
  */
 public class ConnPoolByRoute extends AbstractConnPool {
         
     private final Log log = LogFactory.getLog(getClass());
 
-    protected final HttpParams params;
+    private final HttpParams params;
     
     /** Connection operator for this pool */
     protected final ClientConnectionOperator operator;

httpclient/src/main/java/org/apache/http/impl/conn/tsccm/ThreadSafeClientConnManager.java

@@ -46,19 +46,32 @@ import org.apache.http.conn.OperatedClientConnection;
 import org.apache.http.params.HttpParams;
 import org.apache.http.impl.conn.DefaultClientConnectionOperator;
 
-
-
 /**
- * Manages a pool of {@link OperatedClientConnection client connections}.
+ * Manages a pool of {@link OperatedClientConnection client connections} and 
+ * is able to service connection requests from multiple execution threads. 
+ * Connections are pooled on a per route basis. A request for a route which 
+ * already the manager has persistent connections for available in the pool 
+ * will be services by leasing a connection from the pool rather than 
+ * creating a brand new connection.
  * <p>
- * This class is derived from <code>MultiThreadedHttpConnectionManager</code>
+ * ThreadSafeClientConnManager maintains a maximum limit of connection on 
- * in HttpClient 3. See there for original authors.
+ * a per route basis and in total. Per default this implementation will
- * </p>
+ * create no more than than 2 concurrent connections per given route 
+ * and no more 20 connections in total. For many real-world applications
+ * these limits may prove too constraining, especially if they use HTTP
+ * as a transport protocol for their services. Connection limits, however,
+ * can be adjusted using HTTP parameters.
+ * <p>
+ * The following parameters can be used to customize the behavior of this 
+ * class: 
+ * <ul>
+ *  <li>{@link org.apache.http.conn.params.ConnManagerPNames#MAX_TOTAL_CONNECTIONS}</li>
+ *  <li>{@link org.apache.http.conn.params.ConnManagerPNames#MAX_CONNECTIONS_PER_ROUTE}</li>
+ *  <li>{@link org.apache.http.conn.params.ConnManagerPNames#TIMEOUT}</li>
+ * </ul>
  *
- *
+ * @see org.apache.http.conn.params.ConnPerRoute 
- *
+ * @see org.apache.http.conn.params.ConnPerRouteBean
- * <!-- empty lines to avoid svn diff problems -->
- * @version $Revision$ $Date$
  *
  * @since 4.0
  */
@@ -75,8 +88,6 @@ public class ThreadSafeClientConnManager implements ClientConnectionManager {
     /** The operator for opening and updating connections. */
     protected final ClientConnectionOperator connOperator;
     
-
-
     /**
      * Creates a new thread safe connection manager.
      *
@@ -94,16 +105,14 @@ public class ThreadSafeClientConnManager implements ClientConnectionManager {
         this.connOperator   = createConnectionOperator(schreg);
         this.connectionPool = createConnectionPool(params);
 
-    } // <constructor>
+    }
 
-    
     @Override
     protected void finalize() throws Throwable {
         shutdown();
         super.finalize();
     }
 
-
     /**
      * Hook for creating the connection pool.
      *
@@ -119,7 +128,6 @@ public class ThreadSafeClientConnManager implements ClientConnectionManager {
         return acp;
     }
 
-
     /**
      * Hook for creating the connection operator.
      * It is called by the constructor.
@@ -138,13 +146,10 @@ public class ThreadSafeClientConnManager implements ClientConnectionManager {
         return new DefaultClientConnectionOperator(schreg);
     }
 
-
-    // non-javadoc, see interface ClientConnectionManager
     public SchemeRegistry getSchemeRegistry() {
         return this.schemeRegistry;
     }
 
-    
     public ClientConnectionRequest requestConnection(
             final HttpRoute route, 
             final Object state) {
@@ -178,8 +183,6 @@ public class ThreadSafeClientConnManager implements ClientConnectionManager {
         
     }
 
-    
-    // non-javadoc, see interface ClientConnectionManager
     public void releaseConnection(ManagedClientConnection conn, long validDuration, TimeUnit timeUnit) {
 
         if (!(conn instanceof BasicPooledConnAdapter)) {
@@ -228,14 +231,11 @@ public class ThreadSafeClientConnManager implements ClientConnectionManager {
         }
     }
 
-
-    // non-javadoc, see interface ClientConnectionManager
     public void shutdown() {
         log.debug("Shutting down");
         connectionPool.shutdown();
     }
 
-
     /**
      * Gets the total number of pooled connections for the given route.
      * This is the total number of connections that have been created and
@@ -251,7 +251,6 @@ public class ThreadSafeClientConnManager implements ClientConnectionManager {
                 route);
     }
 
-
     /**
      * Gets the total number of pooled connections.  This is the total number of 
      * connections that have been created and are still in use by this connection 
@@ -268,8 +267,6 @@ public class ThreadSafeClientConnManager implements ClientConnectionManager {
         return count;
     }
 
-
-    // non-javadoc, see interface ClientConnectionManager
     public void closeIdleConnections(long idleTimeout, TimeUnit tunit) {
         if (log.isDebugEnabled()) {
             log.debug("Closing connections idle for " + idleTimeout + " " + tunit);
@@ -284,6 +281,5 @@ public class ThreadSafeClientConnManager implements ClientConnectionManager {
         connectionPool.deleteClosedConnections();
     }
 
-
+}
-} // class ThreadSafeClientConnManager
 

httpclient/src/test/java/org/apache/http/impl/conn/TestSCMWithServer.java

@@ -236,4 +236,26 @@ public class TestSCMWithServer extends ServerTestBase {
         mgr.shutdown();
     }
     
+    public void testAlreadyLeased() throws Exception {
+
+        HttpParams mgrpar = defaultParams.copy();
+        ConnManagerParams.setMaxTotalConnections(mgrpar, 1);
+
+        SingleClientConnManager mgr = createSCCM(mgrpar, null);
+
+        final HttpHost target = getServerHttp();
+        final HttpRoute route = new HttpRoute(target, null, false);
+
+        ManagedClientConnection conn =  mgr.getConnection(route, null);
+        mgr.releaseConnection(conn, 100, TimeUnit.MILLISECONDS);
+        
+        mgr.getConnection(route, null);
+        try {
+            mgr.getConnection(route, null);
+            fail("IllegalStateException should have been thrown");
+        } catch (IllegalStateException ex) {
+            mgr.shutdown();
+        }
+    }
+
 }