Javadoc cleanups; fixed some binary incompatibilities with 4.0-beta1

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

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

@@ -96,6 +96,11 @@ import org.apache.http.protocol.HttpContext;
  *         instream.close();
  *         
  *     }
+ *     
+ *     // When HttpClient instance is no longer needed, 
+ *     // shut down the connection manager to ensure
+ *     // immediate deallocation of all system resources
+ *     httpclient.getConnectionManager().shutdown();        
  * }
  * </PRE>
  *

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

@@ -40,9 +40,8 @@ import org.apache.http.protocol.HttpContext;
  * <code>null</code> if the context does not contain any resources or details 
  * specific to the current user.
  * <p/>
- * The user token will be used to ensure that user specific resouces will not
+ * The user token will be used to ensure that user specific resources will not
- * shared with or reused by other users.
+ * be shared with or reused by other users.
- *
  * 
  * @since 4.0
  */

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

@@ -60,7 +60,8 @@ public interface ClientPNames {
     public static final String HANDLE_REDIRECTS = "http.protocol.handle-redirects";
 
     /**
-     * Defines whether relative redirects should be rejected.
+     * Defines whether relative redirects should be rejected. HTTP specification 
+     * requires the location value be an absolute URI.
      * <p>
      * This parameter expects a value of type {@link Boolean}.
      * </p>

httpclient/src/main/java/org/apache/http/client/protocol/ClientContext.java

@@ -97,6 +97,10 @@ public interface ClientContext {
      */
     public static final String AUTH_SCHEME_PREF      = "http.auth.scheme-pref";
     
+    /**
+     * Attribute name of a {@link java.lang.Object} object that represents 
+     * the actual user identity such as user {@link java.security.Principal}.
+     */
     public static final String USER_TOKEN            = "http.user-token";
     
 }

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

@@ -71,10 +71,14 @@ import org.apache.http.protocol.HttpProcessor;
 import org.apache.http.protocol.HttpRequestExecutor;
 
 /**
- * Base class for {@link HttpClient} implementations.
+ * Base class for {@link HttpClient} implementations. This class acts as 
- * <p>
+ * a facade to a number of special purpose handler or strategy 
- * This class maintains a number of objects used during HTTP request execution 
+ * implementations responsible for handling of a particular aspect of 
- * and provides a number of factory methods to instantiate those objects:
+ * the HTTP protocol such as redirect or authentication handling or 
+ * making decision about connection persistence and keep alive duration. 
+ * This enables the users to selectively replace default implementation 
+ * of those aspects with custom, application specific ones. This class 
+ * also provides factory methods to instantiate those objects:
  * <ul>
  *   <li>{@link HttpRequestExecutor}</li> object used to transmit messages 
  *    over HTTP connections. The {@link #createRequestExecutor()} must be
@@ -130,8 +134,25 @@ import org.apache.http.protocol.HttpRequestExecutor;
  *    response received from the target server. 
  *    The {@link #createRedirectHandler()} must be implemented 
  *    by concrete super classes to instantiate this object.
- *   <li>{@link UserTokenHandler}</li>
+ *   <li>{@link UserTokenHandler}</li> object used to determine if the 
+ *    execution context is user identity specific. 
+ *    The {@link #createUserTokenHandler()()} must be implemented by 
+ *    concrete super classes to instantiate this object.
  * </ul> 
+ * <p>
+ *   This class also maintains a list of protocol interceptors intended 
+ *   for processing outgoing requests and incoming responses and provides 
+ *   methods for managing those interceptors. New protocol interceptors can be 
+ *   introduced to the protocol processor chain or removed from it if needed. 
+ *   Internally protocol interceptors are stored in a simple 
+ *   {@link java.util.ArrayList}. They are executed in the same natural order 
+ *   as they are added to the list.
+ * <p>
+ *   AbstractHttpClient is thread safe. It is recommended that the same 
+ *   instance of this class is reused for multiple request executions. 
+ *   When an instance of DefaultHttpClient is no longer needed and is about 
+ *   to go out of scope the connection manager associated with it must be 
+ *   shut down by calling {@link ClientConnectionManager#shutdown()}!
  *
  * @since 4.0
  */

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

@@ -86,16 +86,73 @@ import org.apache.http.protocol.RequestTargetHost;
 import org.apache.http.protocol.RequestUserAgent;
 import org.apache.http.util.VersionInfo;
 
-
-
 /**
- * Default implementation of an HTTP client.
+ * Default implementation of {@link AbstractHttpClient}.
- * <br/>
+ * <p>
- * This class replaces <code>HttpClient</code> in HttpClient 3.
+ * This class creates an instance of {@link SingleClientConnManager}
- *
+ * for connection management if not explicitly set.
- *
+ * <p>
- * <!-- empty lines to avoid svn diff problems -->
+ * This class creates the following chain of protocol interceptors per 
- * @version   $Revision$
+ * default:
+ * <ul>
+ * <li>{@link RequestDefaultHeaders}</li>
+ * <li>{@link RequestContent}</li>
+ * <li>{@link RequestTargetHost}</li>
+ * <li>{@link RequestConnControl}</li>
+ * <li>{@link RequestUserAgent}</li>
+ * <li>{@link RequestExpectContinue}</li>
+ * <li>{@link RequestAddCookies}</li>
+ * <li>{@link ResponseProcessCookies}</li>
+ * <li>{@link RequestTargetAuthentication}</li>
+ * <li>{@link RequestProxyAuthentication}</li>
+ * </ul>
+ * <p>
+ * This class sets up the following parameters if not explicitly set:
+ * <ul>
+ * <li>Version: HttpVersion.HTTP_1_1</li>
+ * <li>ContentCharset: HTTP.DEFAULT_CONTENT_CHARSET</li>
+ * <li>UseExpectContinue: true</li>
+ * <li>NoTcpDelay: true</li>
+ * <li>SocketBufferSize: 8192</li>
+ * <li>UserAgent: Apache-HttpClient/release (java 1.5)</li>
+ * </ul>
+ * <p>
+ * The following parameters can be used to customize the behavior of this 
+ * class: 
+ * <ul>
+ *  <li>{@link org.apache.http.params.CoreProtocolPNames#PROTOCOL_VERSION}</li>
+ *  <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.CoreProtocolPNames#USE_EXPECT_CONTINUE}</li>
+ *  <li>{@link org.apache.http.params.CoreProtocolPNames#WAIT_FOR_CONTINUE}</li>
+ *  <li>{@link org.apache.http.params.CoreProtocolPNames#USER_AGENT}</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>
+ *  <li>{@link org.apache.http.params.CoreConnectionPNames#SO_TIMEOUT}</li>
+ *  <li>{@link org.apache.http.params.CoreConnectionPNames#SO_LINGER}</li>
+ *  <li>{@link org.apache.http.params.CoreConnectionPNames#TCP_NODELAY}</li>
+ *  <li>{@link org.apache.http.params.CoreConnectionPNames#CONNECTION_TIMEOUT}</li>
+ *  <li>{@link org.apache.http.params.CoreConnectionPNames#STALE_CONNECTION_CHECK}</li>
+ *  <li>{@link org.apache.http.conn.params.ConnRoutePNames#FORCED_ROUTE}</li>
+ *  <li>{@link org.apache.http.conn.params.ConnRoutePNames#LOCAL_ADDRESS}</li>
+ *  <li>{@link org.apache.http.conn.params.ConnRoutePNames#DEFAULT_PROXY}</li>
+ *  <li>{@link org.apache.http.conn.params.ConnManagerPNames#TIMEOUT}</li>
+ *  <li>{@link org.apache.http.conn.params.ConnManagerPNames#MAX_CONNECTIONS_PER_ROUTE}</li>
+ *  <li>{@link org.apache.http.conn.params.ConnManagerPNames#MAX_TOTAL_CONNECTIONS}</li>
+ *  <li>{@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}</li>
+ *  <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#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>
+ *  <li>{@link org.apache.http.client.params.ClientPNames#CONNECTION_MANAGER_FACTORY_CLASS_NAME}</li>
+ * </ul>
  *
  * @since 4.0
  */
@@ -126,17 +183,6 @@ public class DefaultHttpClient extends AbstractHttpClient {
     }
 
     
-    /**
-     * Creates a new BasicHttpParams object, and sets up the following:
-     * <ul>
-     * <li>Version: HttpVersion.HTTP_1_1</li>
-     * <li>ContentCharset: HTTP.DEFAULT_CONTENT_CHARSET</li>
-     * <li>UseExpectContinue: true</li>
-     * <li>NoTcpDelay: true</li>
-     * <li>SocketBufferSize: 8192</li>
-     * <li>UserAgent: Apache-HttpClient/release (java 1.5)</li>
-     * </ul>
-     */
     @Override
     protected HttpParams createHttpParams() {
         HttpParams params = new BasicHttpParams();

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

@@ -52,15 +52,9 @@ import org.apache.http.params.HttpParams;
 import org.apache.http.protocol.HttpContext;
 import org.apache.http.protocol.ExecutionContext;
 
-
 /**
  * Default implementation of {@link RedirectHandler}.
  *
- *
- *
- * <!-- empty lines to avoid svn diff problems -->
- * @version $Revision$
- *
  * @since 4.0
  */
 @Immutable

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

@@ -534,11 +534,14 @@ public class DefaultRequestDirector implements RequestDirector {
                     roureq = followup;
                 }
 
-                userToken = this.userTokenHandler.getUserToken(context);
+                if (managedConn != null && userToken == null) {
+                    userToken = userTokenHandler.getUserToken(context);
                     context.setAttribute(ClientContext.USER_TOKEN, userToken);
-                if (managedConn != null) {
+                    if (userToken != null) {
                         managedConn.setState(userToken);
                     }
+                }
+                
             } // while not done
 
 

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

@@ -46,6 +46,16 @@ import org.apache.http.protocol.ExecutionContext;
 import org.apache.http.protocol.HttpContext;
 
 /**
+ * Default implementation of {@link UserTokenHandler}. This class will use 
+ * an instance of {@link Principal} as a state object for HTTP connections, 
+ * if it can be obtained from the given execution context. This helps ensure 
+ * persistent connections created with a particular user identity within 
+ * a particular security context can be reused by the same user only.
+ * <p>
+ * DefaultUserTokenHandler will use the user principle of connection
+ * based authentication schemes such as NTLM or that of the SSL session 
+ * with the client authentication turned on. If both are unavailable, 
+ * <code>null</code> token will be returned.   
  *
  * @since 4.0
  */

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

@@ -35,22 +35,16 @@ import net.jcip.annotations.NotThreadSafe;
 
 import org.apache.http.conn.routing.HttpRoute;
 
-
 /**
  * A request with the route along which it should be sent.
  *
- *
- *
- * <!-- empty lines to avoid svn diff problems -->
- * @version $Revision$
- *
  * @since 4.0
  */
 @NotThreadSafe // RequestWrapper is @NotThreadSafe
 public class RoutedRequest {
 
-    private final RequestWrapper request; // @NotThreadSafe
+    protected final RequestWrapper request; // @NotThreadSafe
-    private final HttpRoute route; // @Immutable
+    protected final HttpRoute route; // @Immutable
 
     /**
      * Creates a new routed request.

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

@@ -91,11 +91,7 @@ public class BestMatchSpec implements CookieSpec {
 
     private NetscapeDraftSpec getNetscape() {
         if (this.netscape == null) {
-            String[] patterns = this.datepatterns;
+            this.netscape = new NetscapeDraftSpec(this.datepatterns);
-            if (patterns == null) {
-                patterns = BrowserCompatSpec.getDATE_PATTERNS();
-            }
-            this.netscape = new NetscapeDraftSpec(patterns);
         }
         return netscape;
     }

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

@@ -57,8 +57,25 @@ import org.apache.http.util.CharArrayBuffer;
  */
 public class BrowserCompatSpec extends CookieSpecBase {
     
-    /** Valid date patterns used per default */
+    @Deprecated
-    private static final String[] DATE_PATTERNS = new String[] {
+    protected static final String[] DATE_PATTERNS = new String[] {
+            DateUtils.PATTERN_RFC1123,
+            DateUtils.PATTERN_RFC1036,
+            DateUtils.PATTERN_ASCTIME,
+            "EEE, dd-MMM-yyyy HH:mm:ss z",
+            "EEE, dd-MMM-yyyy HH-mm-ss z",
+            "EEE, dd MMM yy HH:mm:ss z",
+            "EEE dd-MMM-yyyy HH:mm:ss z",
+            "EEE dd MMM yyyy HH:mm:ss z",
+            "EEE dd-MMM-yyyy HH-mm-ss z",
+            "EEE dd-MMM-yy HH:mm:ss z",
+            "EEE dd MMM yy HH:mm:ss z",
+            "EEE,dd-MMM-yy HH:mm:ss z",
+            "EEE,dd-MMM-yyyy HH:mm:ss z",
+            "EEE, dd-MM-yyyy HH:mm:ss z",                
+        };
+
+    private static final String[] DEFAULT_DATE_PATTERNS = new String[] {
         DateUtils.PATTERN_RFC1123,
         DateUtils.PATTERN_RFC1036,
         DateUtils.PATTERN_ASCTIME,
@@ -83,7 +100,7 @@ public class BrowserCompatSpec extends CookieSpecBase {
         if (datepatterns != null) {
             this.datepatterns = datepatterns.clone();
         } else {
-            this.datepatterns = DATE_PATTERNS;
+            this.datepatterns = DEFAULT_DATE_PATTERNS;
         }
         registerAttribHandler(ClientCookie.PATH_ATTR, new BasicPathHandler());
         registerAttribHandler(ClientCookie.DOMAIN_ATTR, new BasicDomainHandler());
@@ -189,10 +206,6 @@ public class BrowserCompatSpec extends CookieSpecBase {
         return null;
     }
 
-    protected static String[] getDATE_PATTERNS() {
-        return DATE_PATTERNS.clone();
-    }
-    
     @Override
     public String toString() {
         return "compatibility";