Javadoc updates

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

httpclient/src/main/java/org/apache/http/client/AuthenticationHandler.java

@@ -41,19 +41,59 @@ import org.apache.http.auth.MalformedChallengeException;
 import org.apache.http.protocol.HttpContext;
 
 /**
+/**
+ * A handler for determining if an HTTP response represents an authentication 
+ * challenge that was sent back to the client as a result of authentication 
+ * failure.
+ * <p>
+ * Implementations of this interface must be thread-safe. Access to shared
+ * data must be synchronized as methods of this interface may be executed 
+ * from multiple threads.
  *
  * @since 4.0
  */
 public interface AuthenticationHandler {
 
+    /**
+     * Determines if the given HTTP response response represents 
+     * an authentication challenge that was sent back as a result 
+     * of authentication failure
+     * @param response HTTP response.
+     * @param context HTTP context.
+     * @return <code>true</code> if user authentication is required,
+     *   <code>false</code> otherwise.
+     */
     boolean isAuthenticationRequested(
             HttpResponse response, 
             HttpContext context);
 
+    /**
+     * Extracts from the given HTTP response a collection of authentication 
+     * challenges, each of which represents an authentication scheme supported
+     * by the authentication host.   
+     * 
+     * @param response HTTP response.
+     * @param context HTTP context.
+     * @return a collection of challenges keyed by names of corresponding 
+     * authentication schemes. 
+     * @throws MalformedChallengeException if one of the authentication 
+     *  challenges is not valid or malformed.
+     */
     Map<String, Header> getChallenges(
             HttpResponse response, 
             HttpContext context) throws MalformedChallengeException;
     
+    /**
+     * Selects one authentication challenge out of all available and
+     * creates and generates {@link AuthScheme} instance capable of
+     * processing that challenge.
+     * @param challenges collection of challenges.
+     * @param response HTTP response.
+     * @param context HTTP context.
+     * @return authentication scheme to use for authentication.
+     * @throws AuthenticationException if an authentication scheme
+     *  could not be selected.
+     */
     AuthScheme selectScheme(
             Map<String, Header> challenges, 
             HttpResponse response, 

httpclient/src/main/java/org/apache/http/client/CredentialsProvider.java

@@ -34,8 +34,12 @@ import org.apache.http.auth.AuthScope;
 import org.apache.http.auth.Credentials;
 
 /**
- * Abstract credentials provider.
+ * Abstract credentials provider that maintains a collection of user 
- * 
+ * credentials.
+ * <p>
+ * Implementations of this interface must be thread-safe. Access to shared
+ * data must be synchronized as methods of this interface may be executed 
+ * from multiple threads.
  * 
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/client/HttpClient.java

@@ -42,15 +42,14 @@ import org.apache.http.params.HttpParams;
 import org.apache.http.protocol.HttpContext;
 
 /**
- * Interface for an HTTP client.
+ * This interface represents only the most basic contract for HTTP request 
- * HTTP clients act as a facade to a number of objects required to
+ * execution. It imposes no restrictions or particular details on the request 
- * execute HTTP requests while handling cookies, authentication,
+ * execution process and leaves the specifics of state management, 
- * connection management, and other features.
+ * authentication and redirect handling up to individual implementations. 
- * Thread safety of HTTP clients depends on the implementation
+ * This should make it easier to decorate the interface with additional 
- * and configuration of the specific client.
+ * functionality such as response content caching.  
  * <p/>
- * The usual execution flow can be demonstrated by the 
+ * The usual execution flow can be demonstrated by the code snippet below:
- * code snippet below:
  * <PRE>
  * HttpClient httpclient = new DefaultHttpClient();
  * 
@@ -100,11 +99,6 @@ import org.apache.http.protocol.HttpContext;
  * }
  * </PRE>
  *
- *
- *
- * <!-- empty lines to avoid svn diff problems -->
- * @version   $Revision$
- *
  * @since 4.0
  */
 public interface HttpClient {
@@ -118,17 +112,14 @@ public interface HttpClient {
      *
      * @return  the default parameters
      */
-    HttpParams getParams()
+    HttpParams getParams();
-        ;
-
 
     /**
      * Obtains the connection manager used by this client.
      *
      * @return  the connection manager
      */
-    ClientConnectionManager getConnectionManager()
+    ClientConnectionManager getConnectionManager();
-        ;
 
     /**
      * Executes a request using the default context.
@@ -144,9 +135,7 @@ public interface HttpClient {
      * @throws ClientProtocolException in case of an http protocol error
      */
     HttpResponse execute(HttpUriRequest request)
-        throws IOException, ClientProtocolException
+        throws IOException, ClientProtocolException;
-        ;
-
 
     /**
      * Executes a request using the given context.
@@ -165,9 +154,7 @@ public interface HttpClient {
      * @throws ClientProtocolException in case of an http protocol error
      */
     HttpResponse execute(HttpUriRequest request, HttpContext context)
-        throws IOException, ClientProtocolException
+        throws IOException, ClientProtocolException;
-        ;
-
 
     /**
      * Executes a request to the target using the default context.
@@ -187,8 +174,7 @@ public interface HttpClient {
      * @throws ClientProtocolException in case of an http protocol error
      */
     HttpResponse execute(HttpHost target, HttpRequest request)
-        throws IOException, ClientProtocolException
+        throws IOException, ClientProtocolException;
-        ;
 
     /**
      * Executes a request to the target using the given context.
@@ -211,8 +197,7 @@ public interface HttpClient {
      */
     HttpResponse execute(HttpHost target, HttpRequest request,
                          HttpContext context)
-        throws IOException, ClientProtocolException
+        throws IOException, ClientProtocolException;
-        ;
 
     /**
      * Executes a request using the default context and processes the
@@ -228,8 +213,7 @@ public interface HttpClient {
     <T> T execute(
             HttpUriRequest request, 
             ResponseHandler<? extends T> responseHandler)
-        throws IOException, ClientProtocolException
+        throws IOException, ClientProtocolException;
-        ;
 
     /**
      * Executes a request using the given context and processes the
@@ -246,8 +230,7 @@ public interface HttpClient {
             HttpUriRequest request, 
             ResponseHandler<? extends T> responseHandler,
             HttpContext context)
-        throws IOException, ClientProtocolException
+        throws IOException, ClientProtocolException;
-        ;
 
     /**
      * Executes a request to the target using the default context and 
@@ -268,8 +251,7 @@ public interface HttpClient {
             HttpHost target, 
             HttpRequest request,
             ResponseHandler<? extends T> responseHandler)
-        throws IOException, ClientProtocolException
+        throws IOException, ClientProtocolException;
-        ;
     
     /**
      * Executes a request to the target using the given context and 
@@ -293,7 +275,6 @@ public interface HttpClient {
             HttpRequest request,
             ResponseHandler<? extends T> responseHandler, 
             HttpContext context)
-        throws IOException, ClientProtocolException
+        throws IOException, ClientProtocolException;
-        ;
     
-} // interface HttpClient
+}

httpclient/src/main/java/org/apache/http/client/HttpRequestRetryHandler.java

@@ -38,12 +38,10 @@ import org.apache.http.protocol.HttpContext;
 /**
  * A handler for determining if an HttpRequest should be retried after a 
  * recoverable exception during execution.
- * 
  * <p>
- * Classes implementing this interface must synchronize access to shared
+ * Implementations of this interface must be thread-safe. Access to shared
- * data as methods of this interfrace may be executed from multiple threads 
+ * data must be synchronized as methods of this interface may be executed 
- * </p>
+ * from multiple threads.
- * 
  *
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/client/RedirectHandler.java

@@ -41,12 +41,10 @@ import org.apache.http.protocol.HttpContext;
  * A handler for determining if an HTTP request should be redirected to 
  * a new location in response to an HTTP response received from the target
  * server.
- * 
  * <p>
- * Classes implementing this interface must synchronize access to shared
+ * Implementations of this interface must be thread-safe. Access to shared
- * data as methods of this interfrace may be executed from multiple threads 
+ * data must be synchronized as methods of this interface may be executed 
- * </p>
+ * from multiple threads.
- * 
  *
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/client/RequestDirector.java

@@ -46,17 +46,6 @@ import org.apache.http.protocol.HttpContext;
  * authentication challenges. The director may therefore generate and
  * send a sequence of requests in order to execute one initial request.
  *
- * <br/><b>Note:</b>
- * It is most likely that implementations of this interface will
- * allocate connections, and return responses that depend on those
- * connections for reading the response entity. Such connections
- * MUST be released, but that is out of the scope of a request director.
- *
- *
- *
- * <!-- empty lines to avoid svn diff problems -->
- * @version $Revision$
- *
  * @since 4.0
  */
 public interface RequestDirector {
@@ -83,9 +72,7 @@ public interface RequestDirector {
      * @throws IOException              in case of an IO problem
      *                                     or if the connection was aborted
      */
-    HttpResponse execute(HttpHost target, HttpRequest request,
+    HttpResponse execute(HttpHost target, HttpRequest request, HttpContext context)
-                         HttpContext context)
+        throws HttpException, IOException;
-        throws HttpException, IOException
-        ;
 
-} // class ClientRequestDirector
+}

httpclient/src/main/java/org/apache/http/client/entity/package.html

@@ -0,0 +1,40 @@
+<html>
+<head>
+<!--
+/*
+ * $HeadURL:$
+ * $Revision:$
+ * $Date:$
+ *
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+-->
+</head>
+<body>
+Additional HTTP entity implementations that depend on HttpClient
+specific features.
+</body>
+</html>

httpclient/src/main/java/org/apache/http/client/methods/HttpEntityEnclosingRequestBase.java

@@ -38,10 +38,8 @@ import org.apache.http.client.utils.CloneUtils;
 import org.apache.http.protocol.HTTP;
 
 /**
- * Basic implementation of an HTTP request that can be modified.
+ * Basic implementation of an entity enclosing HTTP request 
- *
+ * that can be modified
- *
- * @version $Revision$
  * 
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/client/package.html

@@ -34,8 +34,7 @@
 -->
 </head>
 <body>
-The API for client-side HTTP communication and
+The API for client-side HTTP communication.
-entry point to the <i>HttpClient</i> module.
 <p/>
 The usual execution flow can be demonstrated by the 
 code snippet below:

httpclient/src/main/java/org/apache/http/client/params/AuthPolicy.java

@@ -34,6 +34,7 @@ package org.apache.http.client.params;
 import net.jcip.annotations.Immutable;
 
 /**
+ * Standard authentication schemes supported by HttpClient. 
  *
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/client/params/ClientPNames.java

@@ -30,13 +30,8 @@
 
 package org.apache.http.client.params;
 
-
 /**
- * Parameter names for the HttpClient module.
+ * Parameter names for HTTP client parameters.
- * This does not include parameters for informational units
- * HttpAuth, HttpCookie, or HttpConn.
- *
- * @version $Revision$
  * 
  * @since 4.0
  */
@@ -51,11 +46,9 @@ public interface ClientPNames {
     public static final String CONNECTION_MANAGER_FACTORY_CLASS_NAME = "http.connection-manager.factory-class-name";
     
     /**
-     * Defines the factory to create a default {@link org.apache.http.conn.ClientConnectionManager}.
+     * @deprecated use #CONNECTION_MANAGER_FACTORY_CLASS_NAME
-     * <p>
-     * This parameters expects a value of type {@link org.apache.http.conn.ClientConnectionManagerFactory}.
-     * </p>
      */
+    @Deprecated
     public static final String CONNECTION_MANAGER_FACTORY = "http.connection-manager.factory-object";
     
     /** 
@@ -110,7 +103,8 @@ public interface ClientPNames {
     public static final String COOKIE_POLICY = "http.protocol.cookie-policy";
     
     /**
-     * Defines the virtual host name.
+     * Defines the virtual host name to be used in the <code>Host</code> 
+     * request header instead of the physical host name.
      * <p>
      * This parameter expects a value of type {@link org.apache.http.HttpHost}. 
      * </p>

httpclient/src/main/java/org/apache/http/client/params/ClientParamBean.java

@@ -59,6 +59,7 @@ public class ClientParamBean extends HttpAbstractParamBean {
         params.setParameter(ClientPNames.CONNECTION_MANAGER_FACTORY_CLASS_NAME, factory);
     }
     
+    @Deprecated
     public void setConnectionManagerFactory(ClientConnectionManagerFactory factory) {
         params.setParameter(ClientPNames.CONNECTION_MANAGER_FACTORY, factory);
     }

httpclient/src/main/java/org/apache/http/client/params/package.html

@@ -34,7 +34,6 @@
 -->
 </head>
 <body>
-Parameters for configuring <i>HttpClient</i>.
+Parameters for configuring the default HttpClient implementation.
-
 </body>
 </html>

httpclient/src/main/java/org/apache/http/conn/ClientConnectionManager.java

@@ -42,6 +42,10 @@ import org.apache.http.conn.scheme.SchemeRegistry;
  * HTTP connections, manage persistent connections and synchronize access to 
  * persistent connections making sure that only one thread of execution can 
  * have access to a connection at a time.
+ * <p>
+ * Implementations of this interface must be thread-safe. Access to shared
+ * data must be synchronized as methods of this interface may be executed 
+ * from multiple threads.
  *
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/conn/ClientConnectionOperator.java

@@ -45,10 +45,14 @@ import org.apache.http.protocol.HttpContext;
  * {@link OperatedClientConnection} instances and updating the underlying 
  * {@link Socket} of those objects. Implementations will most likely make use 
  * of {@link SocketFactory}s to create {@link Socket} instances.
- * <br/>
+ * <p>
  * The methods in this interface allow the creation of plain and layered
  * sockets. Creating a tunnelled connection through a proxy, however,
  * is not within the scope of the operator.
+ * <p>
+ * Implementations of this interface must be thread-safe. Access to shared
+ * data must be synchronized as methods of this interface may be executed 
+ * from multiple threads.
  *
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/conn/ConnectionKeepAliveStrategy.java

@@ -37,6 +37,10 @@ import org.apache.http.protocol.HttpContext;
 /**
  * Interface for deciding how long a connection can remain
  * idle before being reused.
+ * <p>
+ * Implementations of this interface must be thread-safe. Access to shared
+ * data must be synchronized as methods of this interface may be executed 
+ * from multiple threads.
  * 
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/conn/routing/HttpRoutePlanner.java

@@ -40,6 +40,10 @@ import org.apache.http.protocol.HttpContext;
  * Encapsulates logic to compute a {@link HttpRoute} to a target host.
  * Implementations may for example be based on parameters, or on the
  * standard Java system properties.
+ * <p>
+ * Implementations of this interface must be thread-safe. Access to shared
+ * data must be synchronized as methods of this interface may be executed 
+ * from multiple threads.
  *
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/impl/client/AbstractAuthenticationHandler.java

@@ -57,6 +57,7 @@ import org.apache.http.protocol.HttpContext;
 import org.apache.http.util.CharArrayBuffer;
 
 /**
+ * Base class for {@link AuthenticationHandler} implementations.
  *
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/impl/client/AbstractHttpClient.java

@@ -71,11 +71,67 @@ import org.apache.http.protocol.HttpProcessor;
 import org.apache.http.protocol.HttpRequestExecutor;
 
 /**
- * Convenience base class for HTTP client implementations.
+ * Base class for {@link HttpClient} implementations.
- *
+ * <p>
- *
+ * This class maintains a number of objects used during HTTP request execution 
- * <!-- empty lines to avoid svn diff problems -->
+ * and provides a number of factory methods to instantiate those objects:
- * @version   $Revision$
+ * <ul>
+ *   <li>{@link HttpRequestExecutor}</li> object used to transmit messages 
+ *    over HTTP connections. The {@link #createRequestExecutor()} must be
+ *    implemented by concrete super classes to instantiate this object.  
+ *   <li>{@link BasicHttpProcessor}</li> object to manage a list of protocol 
+ *    interceptors and apply cross-cutting protocol logic to all incoming 
+ *    and outgoing HTTP messages. The {@link #createHttpProcessor()} must be
+ *    implemented by concrete super classes to instantiate this object.
+ *   <li>{@link HttpRequestRetryHandler}</li> object used to decide whether
+ *    or not a failed HTTP request is safe to retry automatically.  
+ *    The {@link #createHttpRequestRetryHandler()} must be
+ *    implemented by concrete super classes to instantiate this object.
+ *   <li>{@link ClientConnectionManager}</li> object used to manage 
+ *    persistent HTTP connections.
+ *   <li>{@link ConnectionReuseStrategy}</li> object used to decide whether 
+ *    or not a HTTP connection can be kept alive and re-used for subsequent 
+ *    HTTP requests. The {@link #createConnectionReuseStrategy()} must be
+ *    implemented by concrete super classes to instantiate this object.
+ *   <li>{@link ConnectionKeepAliveStrategy}</li> object used to decide how
+ *    long a persistent HTTP connection can be kept alive.
+ *    The {@link #createConnectionKeepAliveStrategy()()} must be
+ *    implemented by concrete super classes to instantiate this object.
+ *   <li>{@link CookieSpecRegistry}</li> object used to maintain a list of 
+ *    supported cookie specifications. 
+ *    The {@link #createCookieSpecRegistry()} must be implemented by concrete 
+ *    super classes to instantiate this object.
+ *   <li>{@link CookieStore}</li> object used to maintain a collection of
+ *    cookies. The {@link #createCookieStore()} must be implemented by 
+ *    concrete super classes to instantiate this object.
+ *   <li>{@link AuthSchemeRegistry}</li> object used to maintain a list of 
+ *    supported authentication schemes. 
+ *    The {@link #createAuthSchemeRegistry()} must be implemented by concrete 
+ *    super classes to instantiate this object.
+ *   <li>{@link CredentialsProvider}</li> object used to maintain 
+ *    a collection user credentials. The {@link #createCredentialsProvider()} 
+ *    must be implemented by concrete super classes to instantiate 
+ *    this object.
+ *   <li>{@link AuthenticationHandler}</li> object used to authenticate
+ *    against the target host. 
+ *    The {@link #createTargetAuthenticationHandler()} must be implemented 
+ *    by concrete super classes to instantiate this object.
+ *   <li>{@link AuthenticationHandler}</li> object used to authenticate
+ *    against the proxy host. 
+ *    The {@link #createProxyAuthenticationHandler()} must be implemented 
+ *    by concrete super classes to instantiate this object.
+ *   <li>{@link HttpRoutePlanner}</li> object used to calculate a route
+ *    for establishing a connection to the target host. The route
+ *    may involve multiple intermediate hops. 
+ *    The {@link #createHttpRoutePlanner()} must be implemented 
+ *    by concrete super classes to instantiate this object.
+ *   <li>{@link RedirectHandler}</li> object used to determine if an HTTP 
+ *    request should be redirected to a new location in response to an HTTP 
+ *    response received from the target server. 
+ *    The {@link #createRedirectHandler()} must be implemented 
+ *    by concrete super classes to instantiate this object.
+ *   <li>{@link UserTokenHandler}</li>
+ * </ul> 
  *
  * @since 4.0
  */
@@ -458,8 +514,6 @@ public abstract class AbstractHttpClient implements HttpClient {
         getHttpProcessor().removeRequestInterceptorByClass(clazz);
     }
 
-
-    // non-javadoc, see interface HttpClient
     public final HttpResponse execute(HttpUriRequest request)
         throws IOException, ClientProtocolException {
 
@@ -503,15 +557,12 @@ public abstract class AbstractHttpClient implements HttpClient {
         return target;
     }
 
-    // non-javadoc, see interface HttpClient
     public final HttpResponse execute(HttpHost target, HttpRequest request)
         throws IOException, ClientProtocolException {
 
         return execute(target, request, (HttpContext) null);
     }
 
-
-    // non-javadoc, see interface HttpClient
     public final HttpResponse execute(HttpHost target, HttpRequest request,
                                       HttpContext context)
         throws IOException, ClientProtocolException {
@@ -557,8 +608,7 @@ public abstract class AbstractHttpClient implements HttpClient {
         } catch(HttpException httpException) {
             throw new ClientProtocolException(httpException);
         }
-    } // execute
+    }
-
 
     protected RequestDirector createClientRequestDirector(
             final HttpRequestExecutor requestExec,
@@ -608,8 +658,6 @@ public abstract class AbstractHttpClient implements HttpClient {
             (null, getParams(), req.getParams(), null);
     }
 
-
-    // non-javadoc, see interface HttpClient
     public <T> T execute(
             final HttpUriRequest request, 
             final ResponseHandler<? extends T> responseHandler) 
@@ -617,8 +665,6 @@ public abstract class AbstractHttpClient implements HttpClient {
         return execute(request, responseHandler, null);
     }
 
-
-    // non-javadoc, see interface HttpClient
     public <T> T execute(
             final HttpUriRequest request,
             final ResponseHandler<? extends T> responseHandler, 
@@ -628,8 +674,6 @@ public abstract class AbstractHttpClient implements HttpClient {
         return execute(target, request, responseHandler, context);
     }
 
-
-    // non-javadoc, see interface HttpClient
     public <T> T execute(
             final HttpHost target, 
             final HttpRequest request,
@@ -638,8 +682,6 @@ public abstract class AbstractHttpClient implements HttpClient {
         return execute(target, request, responseHandler, null);
     }
 
-
-    // non-javadoc, see interface HttpClient
     public <T> T execute(
             final HttpHost target, 
             final HttpRequest request,
@@ -694,5 +736,4 @@ public abstract class AbstractHttpClient implements HttpClient {
         return result;
     }
 
-
+}
-} // class AbstractHttpClient

httpclient/src/main/java/org/apache/http/impl/client/ClientParamsStack.java

@@ -31,7 +31,6 @@
 
 package org.apache.http.impl.client;
 
-
 import net.jcip.annotations.NotThreadSafe;
 
 import org.apache.commons.logging.Log;
@@ -39,7 +38,6 @@ import org.apache.commons.logging.LogFactory;
 import org.apache.http.params.HttpParams;
 import org.apache.http.params.AbstractHttpParams;
 
-
 /**
  * Represents a stack of parameter collections.
  * When retrieving a parameter, the stack is searched in a fixed order

httpclient/src/main/java/org/apache/http/impl/client/DefaultConnectionKeepAliveStrategy.java

@@ -47,9 +47,6 @@ import org.apache.http.protocol.HttpContext;
  * The default implementation looks solely at the 'Keep-Alive'
  * header's timeout token.
  * 
- *
- * @version $Revision: $
- * 
  * @since 4.0
  */
 @Immutable

httpclient/src/main/java/org/apache/http/impl/client/DefaultHttpClient.java

@@ -182,10 +182,6 @@ public class DefaultHttpClient extends AbstractHttpClient {
         
         ClientConnectionManagerFactory factory = null;
 
-        // Try first getting the factory directly as an object.
-        factory = (ClientConnectionManagerFactory) params
-                .getParameter(ClientPNames.CONNECTION_MANAGER_FACTORY);
-        if (factory == null) { // then try getting its class name.
         String className = (String) params.getParameter(
                 ClientPNames.CONNECTION_MANAGER_FACTORY_CLASS_NAME);
         if (className != null) {
@@ -200,9 +196,7 @@ public class DefaultHttpClient extends AbstractHttpClient {
                 throw new InstantiationError(ex.getMessage());
             }
         }
-        }
+        if (factory != null) {
-        
-        if(factory != null) {
             connManager = factory.newInstance(params, registry);
         } else {
             connManager = new SingleClientConnManager(getParams(), registry); 

httpclient/src/main/java/org/apache/http/impl/client/DefaultProxyAuthenticationHandler.java

@@ -40,9 +40,12 @@ import org.apache.http.HttpResponse;
 import org.apache.http.HttpStatus;
 import org.apache.http.auth.AUTH;
 import org.apache.http.auth.MalformedChallengeException;
+import org.apache.http.client.AuthenticationHandler;
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * Default {@link AuthenticationHandler} implementation for proxy host 
+ * authentication.
  *
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/impl/client/DefaultRequestDirector.java

@@ -124,9 +124,13 @@ import org.apache.http.protocol.HttpRequestExecutor;
  *  <li>{@link org.apache.http.cookie.params.CookieSpecPNames#SINGLE_COOKIE_HEADER}</li>
  *  <li>{@link org.apache.http.auth.params.AuthPNames#CREDENTIAL_CHARSET}</li>
  *  <li>{@link org.apache.http.client.params.ClientPNames#COOKIE_POLICY}</li>
- *  <li>{@link org.apache.http.client.params.ClientPNames#VIRTUAL_HOST}</li>
+ *  <li>{@link org.apache.http.client.params.ClientPNames#HANDLE_AUTHENTICATION}</li>
+ *  <li>{@link org.apache.http.client.params.ClientPNames#HANDLE_REDIRECTS}</li>
  *  <li>{@link org.apache.http.client.params.ClientPNames#MAX_REDIRECTS}</li>
+ *  <li>{@link org.apache.http.client.params.ClientPNames#ALLOW_CIRCULAR_REDIRECTS}</li>
+ *  <li>{@link org.apache.http.client.params.ClientPNames#VIRTUAL_HOST}</li>
  *  <li>{@link org.apache.http.client.params.ClientPNames#DEFAULT_HOST}</li>
+ *  <li>{@link org.apache.http.client.params.ClientPNames#DEFAULT_HEADERS}</li>
  * </ul>
  *
  * @since 4.0

httpclient/src/main/java/org/apache/http/impl/client/DefaultTargetAuthenticationHandler.java

@@ -40,9 +40,12 @@ import org.apache.http.HttpResponse;
 import org.apache.http.HttpStatus;
 import org.apache.http.auth.AUTH;
 import org.apache.http.auth.MalformedChallengeException;
+import org.apache.http.client.AuthenticationHandler;
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * Default {@link AuthenticationHandler} implementation for target host 
+ * authentication.
  * 
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/impl/client/RoutedRequest.java

@@ -72,4 +72,4 @@ public class RoutedRequest {
         return route;
     }
 
-} // interface RoutedRequest
+}

httpclient/src/main/java/org/apache/http/impl/client/TunnelRefusedException.java

@@ -37,6 +37,7 @@ import org.apache.http.HttpException;
 import org.apache.http.HttpResponse;
 
 /**
+ * Signals that the tunnel request was rejected by the proxy host.
  * 
  * @since 4.0
  */

httpclient/src/main/java/org/apache/http/impl/cookie/NetscapeDraftSpec.java

@@ -42,6 +42,7 @@ import org.apache.http.HeaderElement;
 import org.apache.http.cookie.ClientCookie;
 import org.apache.http.cookie.Cookie;
 import org.apache.http.cookie.CookieOrigin;
+import org.apache.http.cookie.CookieSpec;
 import org.apache.http.cookie.MalformedCookieException;
 import org.apache.http.cookie.SM;
 import org.apache.http.message.BufferedHeader;