Javadoc cleanups

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@774460 13f79535-47bb-0310-9956-ffa450edef68
2009-05-13 18:13:35 +00:00 · 2009-05-13 18:13:35 +00:00 · a757cafada
parent 0e319ed85c
commit a757cafada
36 changed files with 274 additions and 108 deletions
--- a/httpclient/src/main/java/org/apache/http/client/CookieStore.java
+++ b/httpclient/src/main/java/org/apache/http/client/CookieStore.java
@ -36,15 +36,15 @@ import java.util.List;
 import org.apache.http.cookie.Cookie;

 /**
- * Abstract cookie store.
- * 
+ * This interface represents an abstract store for {@link Cookie}
+ * objects.
 * 
 * @since 4.0
 */
 public interface CookieStore {

    /**
-     * Adds an {@link Cookie HTTP cookie}, replacing any existing equivalent cookies.
+     * Adds an {@link Cookie}, replacing any existing equivalent cookies.
     * If the given cookie has already expired it will not be added, but existing 
     * values will still be removed.
     * 
@ -60,8 +60,8 @@ public interface CookieStore {
    List<Cookie> getCookies();

    /**
-     * Removes all of {@link Cookie cookies} in this store that have expired by 
-     * the specified {@link java.util.Date date}. 
+     * Removes all of {@link Cookie}s in this store that have expired by 
+     * the specified {@link java.util.Date}. 
     * 
     * @return true if any cookies were purged.
     */
--- a/httpclient/src/main/java/org/apache/http/client/params/ClientParamBean.java
+++ b/httpclient/src/main/java/org/apache/http/client/params/ClientParamBean.java
@ -42,6 +42,9 @@ import org.apache.http.params.HttpAbstractParamBean;
 import org.apache.http.params.HttpParams;

 /**
+ * This is a Java Bean class that can be used to wrap an instance of 
+ * {@link HttpParams} and manipulate HTTP client parameters using 
+ * Java Beans conventions.
 *
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/client/params/CookiePolicy.java
+++ b/httpclient/src/main/java/org/apache/http/client/params/CookiePolicy.java
@ -34,6 +34,7 @@ package org.apache.http.client.params;
 import net.jcip.annotations.Immutable;

 /**
+ * Standard cookie specifications supported by HttpClient. 
 *
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/client/params/HttpClientParams.java
+++ b/httpclient/src/main/java/org/apache/http/client/params/HttpClientParams.java
@ -37,9 +37,6 @@ import org.apache.http.params.HttpParams;
 /**
 * An adaptor for accessing HTTP client parameters in {@link HttpParams}.
 * 
- * 
- * @version $Revision$
- * 
 * @since 4.0
 */
@Immutable
--- a/httpclient/src/main/java/org/apache/http/client/protocol/ClientContext.java
+++ b/httpclient/src/main/java/org/apache/http/client/protocol/ClientContext.java
@ -31,20 +31,39 @@

 package org.apache.http.client.protocol;

-
 /**
- * {@link org.apache.http.protocol.HttpContext Context}
- * attribute names for client.
+ * {@link org.apache.http.protocol.HttpContext} attribute names for 
+ * client side HTTP protocol processing.
 *
 * @since 4.0
 */
 public interface ClientContext {
    
+    /**
+     * Attribute name of a {@link org.apache.http.cookie.CookieSpecRegistry} 
+     * object that represents the actual cookie specification registry.
+     */
    public static final String COOKIESPEC_REGISTRY   = "http.cookiespec-registry"; 
-    public static final String AUTHSCHEME_REGISTRY   = "http.authscheme-registry"; 
-    public static final String COOKIE_STORE          = "http.cookie-store"; 
+
+    /**
+     * Attribute name of a {@link org.apache.http.cookie.CookieSpec} 
+     * object that represents the actual cookie specification.
+     */
    public static final String COOKIE_SPEC           = "http.cookie-spec"; 
+
+    /**
+     * Attribute name of a {@link org.apache.http.cookie.CookieOrigin} 
+     * object that represents the actual details of the origin server.
+     */
    public static final String COOKIE_ORIGIN         = "http.cookie-origin"; 
+    
+    /**
+     * Attribute name of a {@link org.apache.http.client.CookieStore} 
+     * object that represents the actual cookie store.
+     */
+    public static final String COOKIE_STORE          = "http.cookie-store"; 
+
+    public static final String AUTHSCHEME_REGISTRY   = "http.authscheme-registry"; 
    public static final String CREDS_PROVIDER        = "http.auth.credentials-provider"; 
    public static final String TARGET_AUTH_STATE     = "http.auth.target-scope"; 
    public static final String PROXY_AUTH_STATE      = "http.auth.proxy-scope";
--- a/httpclient/src/main/java/org/apache/http/client/protocol/RequestAddCookies.java
+++ b/httpclient/src/main/java/org/apache/http/client/protocol/RequestAddCookies.java
@ -62,10 +62,15 @@ import org.apache.http.protocol.ExecutionContext;
 /**
 * Request interceptor that matches cookies available in the current
 * {@link CookieStore} to the request being executed and generates 
- * corresponding cookierequest headers.
- *
- *
- * @version $Revision$
+ * corresponding <code>Cookie</code> request headers.
+ * <p>
+ * The following parameters can be used to customize the behavior of this 
+ * class: 
+ * <ul>
+ *  <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.client.params.ClientPNames#COOKIE_POLICY}</li>
+ * </ul>
 * 
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/client/protocol/ResponseProcessCookies.java
+++ b/httpclient/src/main/java/org/apache/http/client/protocol/ResponseProcessCookies.java
@ -54,9 +54,6 @@ import org.apache.http.protocol.HttpContext;
 /**
 * Response interceptor that populates the current {@link CookieStore} with data 
 * contained in response cookies received in the given the HTTP response.
- *
- *
- * @version $Revision$
 * 
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/conn/params/ConnConnectionParamBean.java
+++ b/httpclient/src/main/java/org/apache/http/conn/params/ConnConnectionParamBean.java
@ -37,9 +37,9 @@ import org.apache.http.params.HttpAbstractParamBean;
 import org.apache.http.params.HttpParams;

 /**
- * Allows for setting parameters relating to connections on
- * {@link HttpParams}.  This class ensures that the values set on the params
- * are type-safe. 
+ * This is a Java Bean class that can be used to wrap an instance of 
+ * {@link HttpParams} and manipulate HTTP client connection parameters 
+ * using Java Beans conventions.
 *
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/conn/params/ConnManagerParamBean.java
+++ b/httpclient/src/main/java/org/apache/http/conn/params/ConnManagerParamBean.java
@ -37,9 +37,9 @@ import org.apache.http.params.HttpAbstractParamBean;
 import org.apache.http.params.HttpParams;

 /**
- * Allows for setting parameters relating to connection managers on
- * {@link HttpParams}.  This class ensures that the values set on the params
- * are type-safe. 
+ * This is a Java Bean class that can be used to wrap an instance of 
+ * {@link HttpParams} and manipulate connection manager parameters 
+ * using Java Beans conventions.
 *
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/conn/params/ConnRoutePNames.java
+++ b/httpclient/src/main/java/org/apache/http/conn/params/ConnRoutePNames.java
@ -31,7 +31,7 @@
 package org.apache.http.conn.params;

 /**
- * Parameter names for routing in HttpConn.
+ * Parameter names for connection routing.
 * 
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/conn/params/ConnRouteParamBean.java
+++ b/httpclient/src/main/java/org/apache/http/conn/params/ConnRouteParamBean.java
@ -41,9 +41,9 @@ import org.apache.http.params.HttpAbstractParamBean;
 import org.apache.http.params.HttpParams;

 /**
- * Allows for setting parameters relating to connection routes on
- * {@link HttpParams}.  This class ensures that the values set on the params
- * are type-safe. 
+ * This is a Java Bean class that can be used to wrap an instance of 
+ * {@link HttpParams} and manipulate connection routing parameters 
+ * using Java Beans conventions.
 *
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/cookie/Cookie.java
+++ b/httpclient/src/main/java/org/apache/http/cookie/Cookie.java
@ -34,10 +34,10 @@ package org.apache.http.cookie;
 import java.util.Date;

 /**
- * HTTP "magic-cookie" represents a piece of state information
- * that the HTTP agent and the target server can exchange to maintain 
- * a session.
- * 
+ * Cookie interface represents a token or short packet of state information 
+ * (also referred to as "magic-cookie") that the HTTP agent and the target 
+ * server can exchange to maintain a session. In its simples form an HTTP 
+ * cookie is merely a name / value pair.
 * 
 * @since 4.0
 */
@ -91,14 +91,17 @@ public interface Cookie {
    boolean isPersistent();

    /**
-     * Returns domain attribute of the cookie.
+     * Returns domain attribute of the cookie. The value of the Domain 
+     * attribute specifies the domain for which the cookie is valid.
     * 
-     * @return the value of the domain attribute
+     * @return the value of the domain attribute.
     */
    String getDomain();

    /**
-     * Returns the path attribute of the cookie
+     * Returns the path attribute of the cookie. The value of the Path 
+     * attribute specifies the subset of URLs on the origin server to which 
+     * this cookie applies.
     * 
     * @return The value of the path attribute.
     */
--- a/httpclient/src/main/java/org/apache/http/cookie/CookieAttributeHandler.java
+++ b/httpclient/src/main/java/org/apache/http/cookie/CookieAttributeHandler.java
@ -31,7 +31,7 @@
 package org.apache.http.cookie;

 /**
- * Ths interface represents a cookie attribute handler responsible
+ * This interface represents a cookie attribute handler responsible
 * for parsing, validating, and matching a specific cookie attribute, 
 * such as path, domain, port, etc.
 *
--- a/httpclient/src/main/java/org/apache/http/cookie/CookieIdentityComparator.java
+++ b/httpclient/src/main/java/org/apache/http/cookie/CookieIdentityComparator.java
@ -38,12 +38,9 @@ import net.jcip.annotations.Immutable;

 /**
 * This cookie comparator can be used to compare identity of cookies.
- *  
 * <p>
 *  Cookies are considered identical if their names are equal and 
 *  their domain attributes match ignoring case.
- * </p>
- * 
 *
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/cookie/CookieOrigin.java
+++ b/httpclient/src/main/java/org/apache/http/cookie/CookieOrigin.java
@ -35,10 +35,9 @@ import java.util.Locale;
 import net.jcip.annotations.Immutable;

 /**
- * CookieOrigin class incapsulates details of an origin server that 
+ * CookieOrigin class encapsulates details of an origin server that 
 * are relevant when parsing, validating or matching HTTP cookies.
 * 
- * 
 * @since 4.0
 */
@Immutable
--- a/httpclient/src/main/java/org/apache/http/cookie/CookieSpecFactory.java
+++ b/httpclient/src/main/java/org/apache/http/cookie/CookieSpecFactory.java
@ -34,12 +34,19 @@ package org.apache.http.cookie;
 import org.apache.http.params.HttpParams;

 /**
- * 
+ * Factory for {@link CookieSpec} implementations. 
 *
 * @since 4.0
 */
 public interface CookieSpecFactory {    

+	/**
+	 * Creates an instance of {@link CookieSpec} using given HTTP parameters.
+	 * 
+	 * @param params HTTP parameters.
+	 * 
+	 * @return cookie spec.
+	 */
    CookieSpec newInstance(HttpParams params);

 }
--- a/httpclient/src/main/java/org/apache/http/cookie/SetCookie.java
+++ b/httpclient/src/main/java/org/apache/http/cookie/SetCookie.java
@ -34,10 +34,9 @@ package org.apache.http.cookie;
 import java.util.Date;

 /**
- * This interface represents a <code>SetCookie</code> response header sent by the 
+ * This interface represents a <code>Set-Cookie</code> response header sent by the 
 * origin server to the HTTP agent in order to maintain a conversational state.
 * 
- * 
 * @since 4.0
 */
 public interface SetCookie extends Cookie {
--- a/httpclient/src/main/java/org/apache/http/cookie/SetCookie2.java
+++ b/httpclient/src/main/java/org/apache/http/cookie/SetCookie2.java
@ -32,10 +32,9 @@
 package org.apache.http.cookie;

 /**
- * This interface represents a <code>SetCookie2</code> response header sent by the 
+ * This interface represents a <code>Set-Cookie2</code> response header sent by the 
 * origin server to the HTTP agent in order to maintain a conversational state.
 * 
- * 
 * @since 4.0
 */
 public interface SetCookie2 extends SetCookie {
--- a/httpclient/src/main/java/org/apache/http/cookie/package.html
+++ b/httpclient/src/main/java/org/apache/http/cookie/package.html
@ -34,8 +34,6 @@
 -->
 </head>
 <body>
-The API for client-side state management via cookies,
-commonly referred to as <i>HttpCookie</i>.
-
+The API for client-side state management via cookies.
 </body>
 </html>
--- a/httpclient/src/main/java/org/apache/http/cookie/params/CookieSpecPNames.java
+++ b/httpclient/src/main/java/org/apache/http/cookie/params/CookieSpecPNames.java
@ -32,32 +32,30 @@
 package org.apache.http.cookie.params;

 /**
- * Parameter names for cookie specifications in HttpCookie.
- * 
- * 
- * @version $Revision$
+ * Parameter names for HTTP cookie management classes.
 * 
 * @since 4.0
 */
 public interface CookieSpecPNames {

    /**
-     * Parameter for the date patterns used for parsing.
+     * Defines valid date patterns to be used for parsing non-standard 
+     * <code>expires</code> attribute. Only required for compatibility 
+     * with non-compliant servers that still use <code>expires</code> 
+     * defined in the Netscape draft instead of the standard 
+     * <code>max-age</code> attribute.
     * <p>
     * This parameter expects a value of type {@link java.util.Collection}.
-     * The collection elements are of type {@link String}
-     * and must be compatible with the syntax of
-     * {@link java.text.SimpleDateFormat}.
+     * The collection elements must be of type {@link String} compatible 
+     * with the syntax of {@link java.text.SimpleDateFormat}.
     * </p>
     */
    public static final String DATE_PATTERNS = "http.protocol.cookie-datepatterns";
    
    /**
-     * Parameter for Cookie header formatting.
-     * Defines whether {@link org.apache.http.cookie.Cookie cookies}
-     * should be put on 
-     * a single {@link org.apache.http.Header request header}.
-     * If not, each cookie is formatted in a seperate Cookie header.
+     * Defines whether cookies should be forced into a single 
+     * <code>Cookie</code> request header. Otherwise, each cookie is formatted 
+     * as a separate <code>Cookie</code> header.
     * <p>
     * This parameter expects a value of type {@link Boolean}.
     * </p>
--- a/httpclient/src/main/java/org/apache/http/cookie/params/CookieSpecParamBean.java
+++ b/httpclient/src/main/java/org/apache/http/cookie/params/CookieSpecParamBean.java
@ -39,6 +39,9 @@ import org.apache.http.params.HttpAbstractParamBean;
 import org.apache.http.params.HttpParams;

 /**
+ * This is a Java Bean class that can be used to wrap an instance of 
+ * {@link HttpParams} and manipulate HTTP cookie parameters using Java Beans 
+ * conventions.
 *
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/cookie/params/package.html
+++ b/httpclient/src/main/java/org/apache/http/cookie/params/package.html
@ -34,7 +34,7 @@
 -->
 </head>
 <body>
-Parameters for configuring <i>HttpCookie</i>.
-
+Parameters for configuring HTTP state management 
+related classes.
 </body>
 </html>
--- a/httpclient/src/main/java/org/apache/http/impl/client/AbstractAuthenticationHandler.java
+++ b/httpclient/src/main/java/org/apache/http/impl/client/AbstractAuthenticationHandler.java
@ -32,6 +32,7 @@
 package org.apache.http.impl.client;

 import java.util.Arrays;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
@ -112,7 +113,7 @@ public abstract class AbstractAuthenticationHandler implements AuthenticationHan
        return DEFAULT_SCHEME_PRIORITY;
    }
    
-    public AuthScheme selectScheme(
+	public AuthScheme selectScheme(
            final Map<String, Header> challenges, 
            final HttpResponse response,
            final HttpContext context) throws AuthenticationException {
@ -123,7 +124,8 @@ public abstract class AbstractAuthenticationHandler implements AuthenticationHan
            throw new IllegalStateException("AuthScheme registry not set in HTTP context");
        }
        
-        List<?> authPrefs = (List<?>) context.getAttribute(
+        @SuppressWarnings("unchecked")
+        Collection<String> authPrefs = (Collection<String>) context.getAttribute(
                ClientContext.AUTH_SCHEME_PREF);
        if (authPrefs == null) {
            authPrefs = getAuthPreferences();
@ -135,8 +137,7 @@ public abstract class AbstractAuthenticationHandler implements AuthenticationHan
        }

        AuthScheme authScheme = null;
-        for (int i = 0; i < authPrefs.size(); i++) {
-            String id = (String) authPrefs.get(i);
+        for (String id: authPrefs) {
            Header challenge = challenges.get(id.toLowerCase(Locale.ENGLISH)); 

            if (challenge != null) {
--- a/httpclient/src/main/java/org/apache/http/impl/client/DefaultRequestDirector.java
+++ b/httpclient/src/main/java/org/apache/http/impl/client/DefaultRequestDirector.java
@ -101,8 +101,23 @@ import org.apache.http.protocol.HttpRequestExecutor;
 * 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.ConnManagerPNames#TIMEOUT}</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.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#MAX_REDIRECTS}</li>
 *  <li>{@link org.apache.http.client.params.ClientPNames#DEFAULT_HOST}</li>
--- a/httpclient/src/main/java/org/apache/http/impl/cookie/BasicClientCookie.java
+++ b/httpclient/src/main/java/org/apache/http/impl/cookie/BasicClientCookie.java
@ -42,12 +42,7 @@ import org.apache.http.cookie.ClientCookie;
 import org.apache.http.cookie.SetCookie;

 /**
- * HTTP "magic-cookie" represents a piece of state information
- * that the HTTP agent and the target server can exchange to maintain 
- * a session.
- * 
- * 
- * @version $Revision$
+ * Default implementation of {@link SetCookie}.
 *
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/impl/cookie/BasicClientCookie2.java
+++ b/httpclient/src/main/java/org/apache/http/impl/cookie/BasicClientCookie2.java
@ -38,10 +38,7 @@ import net.jcip.annotations.NotThreadSafe;
 import org.apache.http.cookie.SetCookie2;

 /**
- * HTTP "magic-cookie" represents a piece of state information
- * that the HTTP agent and the target server can exchange to maintain 
- * a session as specified by RFC2965.
- * 
+ * Default implementation of {@link SetCookie2}.
 *
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpec.java
+++ b/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpec.java
@ -43,9 +43,8 @@ import org.apache.http.cookie.SM;
 import org.apache.http.cookie.SetCookie2;

 /**
- * 'Meta' cookie specification that selects a cookie policy depending
- * on the format of the cookie(s)
- * 
+ * 'Meta' cookie specification that picks up a cookie policy based on 
+ * the format of cookies sent with the HTTP response.
 *
 * @since 4.0
 */
--- a/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpecFactory.java
+++ b/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpecFactory.java
@ -31,6 +31,8 @@

 package org.apache.http.impl.cookie;

+import java.util.Collection;
+
 import net.jcip.annotations.Immutable;

 import org.apache.http.cookie.CookieSpec;
@ -39,7 +41,15 @@ import org.apache.http.cookie.params.CookieSpecPNames;
 import org.apache.http.params.HttpParams;

 /**
- * 
+ * {@link CookieSpecFactory} implementation that creates and initializes
+ * {@link BestMatchSpec} instances.
+ * <p>
+ * The following parameters can be used to customize the behavior of this 
+ * class: 
+ * <ul>
+ *  <li>{@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}</li>
+ *  <li>{@link org.apache.http.cookie.params.CookieSpecPNames#SINGLE_COOKIE_HEADER}</li>
+ * </ul>
 *
 * @since 4.0
 */
@ -48,9 +58,18 @@ public class BestMatchSpecFactory implements CookieSpecFactory {

    public CookieSpec newInstance(final HttpParams params) {
        if (params != null) {
-            return new BestMatchSpec(
-                    (String []) params.getParameter(CookieSpecPNames.DATE_PATTERNS), 
-                    params.getBooleanParameter(CookieSpecPNames.SINGLE_COOKIE_HEADER, false));
+        	
+        	String[] patterns = null;
+        	Collection<?> param = (Collection<?>) params.getParameter(
+        			CookieSpecPNames.DATE_PATTERNS);
+        	if (param != null) {
+        		patterns = new String[param.size()];
+        		patterns = param.toArray(patterns);
+        	}
+        	boolean singleHeader = params.getBooleanParameter(
+        			CookieSpecPNames.SINGLE_COOKIE_HEADER, false);        	
+        	
+            return new BestMatchSpec(patterns, singleHeader);
        } else {
            return new BestMatchSpec();
        }
--- a/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpecFactory.java
+++ b/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpecFactory.java
@ -31,6 +31,8 @@

 package org.apache.http.impl.cookie;

+import java.util.Collection;
+
 import net.jcip.annotations.Immutable;

 import org.apache.http.cookie.CookieSpec;
@ -39,7 +41,14 @@ import org.apache.http.cookie.params.CookieSpecPNames;
 import org.apache.http.params.HttpParams;

 /**
- * 
+ * {@link CookieSpecFactory} implementation that creates and initializes
+ * {@link BrowserCompatSpec} instances.
+ * <p>
+ * The following parameters can be used to customize the behavior of this 
+ * class: 
+ * <ul>
+ *  <li>{@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}</li>
+ * </ul>
 *
 * @since 4.0
 */
@ -48,8 +57,15 @@ public class BrowserCompatSpecFactory implements CookieSpecFactory {

    public CookieSpec newInstance(final HttpParams params) {
        if (params != null) {
-            return new BrowserCompatSpec(
-                    (String []) params.getParameter(CookieSpecPNames.DATE_PATTERNS));
+        	
+        	String[] patterns = null;
+        	Collection<?> param = (Collection<?>) params.getParameter(
+        			CookieSpecPNames.DATE_PATTERNS);
+        	if (param != null) {
+        		patterns = new String[param.size()];
+        		patterns = param.toArray(patterns);
+        	}
+            return new BrowserCompatSpec(patterns);
        } else {
            return new BrowserCompatSpec();
        }
--- a/httpclient/src/main/java/org/apache/http/impl/cookie/NetscapeDraftSpec.java
+++ b/httpclient/src/main/java/org/apache/http/impl/cookie/NetscapeDraftSpec.java
@ -49,8 +49,9 @@ import org.apache.http.message.ParserCursor;
 import org.apache.http.util.CharArrayBuffer;

 /**
- * Netscape cookie draft compliant cookie policy
- *
+ * This {@link CookieSpec} implementation conforms to the original draft 
+ * specification published by Netscape Communications. It should be avoided 
+ * unless absolutely necessary for compatibility with legacy code.
 * 
 * @since 4.0 
 */
--- a/httpclient/src/main/java/org/apache/http/impl/cookie/NetscapeDraftSpecFactory.java
+++ b/httpclient/src/main/java/org/apache/http/impl/cookie/NetscapeDraftSpecFactory.java
@ -31,6 +31,8 @@

 package org.apache.http.impl.cookie;

+import java.util.Collection;
+
 import net.jcip.annotations.Immutable;

 import org.apache.http.cookie.CookieSpec;
@ -39,7 +41,14 @@ import org.apache.http.cookie.params.CookieSpecPNames;
 import org.apache.http.params.HttpParams;

 /**
- * 
+ * {@link CookieSpecFactory} implementation that creates and initializes
+ * {@link NetscapeDraftSpec} instances.
+ * <p>
+ * The following parameters can be used to customize the behavior of this 
+ * class: 
+ * <ul>
+ *  <li>{@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}</li>
+ * </ul>
 *
 * @since 4.0
 */
@ -48,8 +57,15 @@ public class NetscapeDraftSpecFactory implements CookieSpecFactory {

    public CookieSpec newInstance(final HttpParams params) {
        if (params != null) {
-            return new NetscapeDraftSpec(
-                    (String []) params.getParameter(CookieSpecPNames.DATE_PATTERNS));
+        	
+        	String[] patterns = null;
+        	Collection<?> param = (Collection<?>) params.getParameter(
+        			CookieSpecPNames.DATE_PATTERNS);
+        	if (param != null) {
+        		patterns = new String[param.size()];
+        		patterns = param.toArray(patterns);
+        	}
+            return new NetscapeDraftSpec(patterns);
        } else {
            return new NetscapeDraftSpec();
        }
--- a/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2109Spec.java
+++ b/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2109Spec.java
@ -43,14 +43,18 @@ import org.apache.http.cookie.ClientCookie;
 import org.apache.http.cookie.Cookie;
 import org.apache.http.cookie.CookieOrigin;
 import org.apache.http.cookie.CookiePathComparator;
+import org.apache.http.cookie.CookieSpec;
 import org.apache.http.cookie.MalformedCookieException;
 import org.apache.http.cookie.SM;
 import org.apache.http.message.BufferedHeader;
 import org.apache.http.util.CharArrayBuffer;

 /**
- * RFC 2109 compliant cookie policy
- *
+ * RFC 2109 compliant {@link CookieSpec} implementation. This is an older
+ * version of the official HTTP state management specification superseded
+ * by RFC 2965.
+ * 
+ * @see RFC2965Spec
 * 
 * @since 4.0 
 */
--- a/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2109SpecFactory.java
+++ b/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2109SpecFactory.java
@ -31,6 +31,8 @@

 package org.apache.http.impl.cookie;

+import java.util.Collection;
+
 import net.jcip.annotations.Immutable;

 import org.apache.http.cookie.CookieSpec;
@ -39,7 +41,15 @@ import org.apache.http.cookie.params.CookieSpecPNames;
 import org.apache.http.params.HttpParams;

 /**
- * 
+ * {@link CookieSpecFactory} implementation that creates and initializes
+ * {@link RFC2109Spec} instances.
+ * <p>
+ * The following parameters can be used to customize the behavior of this 
+ * class: 
+ * <ul>
+ *  <li>{@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}</li>
+ *  <li>{@link org.apache.http.cookie.params.CookieSpecPNames#SINGLE_COOKIE_HEADER}</li>
+ * </ul>
 *
 * @since 4.0
 */
@ -48,9 +58,18 @@ public class RFC2109SpecFactory implements CookieSpecFactory {

    public CookieSpec newInstance(final HttpParams params) {
        if (params != null) {
-            return new RFC2109Spec(
-                    (String []) params.getParameter(CookieSpecPNames.DATE_PATTERNS), 
-                    params.getBooleanParameter(CookieSpecPNames.SINGLE_COOKIE_HEADER, false));
+        	
+        	String[] patterns = null;
+        	Collection<?> param = (Collection<?>) params.getParameter(
+        			CookieSpecPNames.DATE_PATTERNS);
+        	if (param != null) {
+        		patterns = new String[param.size()];
+        		patterns = param.toArray(patterns);
+        	}
+        	boolean singleHeader = params.getBooleanParameter(
+        			CookieSpecPNames.SINGLE_COOKIE_HEADER, false);        	
+        	
+            return new RFC2109Spec(patterns, singleHeader);
        } else {
            return new RFC2109Spec();
        }
--- a/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2965Spec.java
+++ b/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2965Spec.java
@ -43,16 +43,16 @@ import org.apache.http.cookie.ClientCookie;
 import org.apache.http.cookie.Cookie;
 import org.apache.http.cookie.CookieAttributeHandler;
 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;
 import org.apache.http.util.CharArrayBuffer;

 /**
- * <p>RFC 2965 specific cookie management functions.</p>
- * 
+ * RFC 2965 compliant {@link CookieSpec} implementation.
 *
- * @since 3.1
+ * @since 4.0
 */
 public class RFC2965Spec extends RFC2109Spec {

--- a/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2965SpecFactory.java
+++ b/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2965SpecFactory.java
@ -31,6 +31,8 @@

 package org.apache.http.impl.cookie;

+import java.util.Collection;
+
 import net.jcip.annotations.Immutable;

 import org.apache.http.cookie.CookieSpec;
@ -39,7 +41,15 @@ import org.apache.http.cookie.params.CookieSpecPNames;
 import org.apache.http.params.HttpParams;

 /**
- * 
+ * {@link CookieSpecFactory} implementation that creates and initializes
+ * {@link RFC2965Spec} instances.
+ * <p>
+ * The following parameters can be used to customize the behavior of this 
+ * class: 
+ * <ul>
+ *  <li>{@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}</li>
+ *  <li>{@link org.apache.http.cookie.params.CookieSpecPNames#SINGLE_COOKIE_HEADER}</li>
+ * </ul>
 *
 * @since 4.0
 */
@ -48,9 +58,18 @@ public class RFC2965SpecFactory implements CookieSpecFactory {

    public CookieSpec newInstance(final HttpParams params) {
        if (params != null) {
-            return new RFC2965Spec(
-                    (String []) params.getParameter(CookieSpecPNames.DATE_PATTERNS), 
-                    params.getBooleanParameter(CookieSpecPNames.SINGLE_COOKIE_HEADER, false));
+        	
+        	String[] patterns = null;
+        	Collection<?> param = (Collection<?>) params.getParameter(
+        			CookieSpecPNames.DATE_PATTERNS);
+        	if (param != null) {
+        		patterns = new String[param.size()];
+        		patterns = param.toArray(patterns);
+        	}
+        	boolean singleHeader = params.getBooleanParameter(
+        			CookieSpecPNames.SINGLE_COOKIE_HEADER, false);        	
+        	
+            return new RFC2965Spec(patterns, singleHeader);
        } else {
            return new RFC2965Spec();
        }
--- a/httpclient/src/main/java/org/apache/http/impl/cookie/package.html
+++ b/httpclient/src/main/java/org/apache/http/impl/cookie/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>
+Default implementations for interfaces in
+{@link org.apache.http.cookie org.apache.http.cookie}.
+</body>
+</html>