Javadoc cleanups

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

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 
+     * Removes all of {@link Cookie}s in this store that have expired by 
-     * the specified {@link java.util.Date date}. 
+     * the specified {@link java.util.Date}. 
      * 
      * @return true if any cookies were purged.
      */

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
  */

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
  */

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

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}
+ * {@link org.apache.http.protocol.HttpContext} attribute names for 
- * attribute names for client.
+ * 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";

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.
+ * corresponding <code>Cookie</code> request headers.
- *
+ * <p>
- *
+ * The following parameters can be used to customize the behavior of this 
- * @version $Revision$
+ * 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
  */

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

@@ -55,9 +55,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
  */
 @Immutable

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
+ * This is a Java Bean class that can be used to wrap an instance of 
- * {@link HttpParams}.  This class ensures that the values set on the params
+ * {@link HttpParams} and manipulate HTTP client connection parameters 
- * are type-safe. 
+ * using Java Beans conventions.
  *
  * @since 4.0
  */

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
+ * This is a Java Bean class that can be used to wrap an instance of 
- * {@link HttpParams}.  This class ensures that the values set on the params
+ * {@link HttpParams} and manipulate connection manager parameters 
- * are type-safe. 
+ * using Java Beans conventions.
  *
  * @since 4.0
  */

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
  */

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
+ * This is a Java Bean class that can be used to wrap an instance of 
- * {@link HttpParams}.  This class ensures that the values set on the params
+ * {@link HttpParams} and manipulate connection routing parameters 
- * are type-safe. 
+ * using Java Beans conventions.
  *
  * @since 4.0
  */

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
+ * Cookie interface represents a token or short packet of state information 
- * that the HTTP agent and the target server can exchange to maintain 
+ * (also referred to as "magic-cookie") that the HTTP agent and the target 
- * a session.
+ * 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.
      */

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.
  *

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
  */

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

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);
 
 }

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 {

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 {

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,
+The API for client-side state management via cookies.
-commonly referred to as <i>HttpCookie</i>.
-
 </body>
 </html>

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.
+ * Parameter names for HTTP cookie management classes.
- * 
- * 
- * @version $Revision$
  * 
  * @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}
+     * The collection elements must be of type {@link String} compatible 
-     * and must be compatible with the syntax of
+     * with the syntax of {@link java.text.SimpleDateFormat}.
-     * {@link java.text.SimpleDateFormat}.
      * </p>
      */
     public static final String DATE_PATTERNS = "http.protocol.cookie-datepatterns";
     
     /**
-     * Parameter for Cookie header formatting.
+     * Defines whether cookies should be forced into a single 
-     * Defines whether {@link org.apache.http.cookie.Cookie cookies}
+     * <code>Cookie</code> request header. Otherwise, each cookie is formatted 
-     * should be put on 
+     * as a separate <code>Cookie</code> header.
-     * a single {@link org.apache.http.Header request header}.
-     * If not, each cookie is formatted in a seperate Cookie header.
      * <p>
      * This parameter expects a value of type {@link Boolean}.
      * </p>

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
  */

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>

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;
@@ -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++) {
+        for (String id: authPrefs) {
-            String id = (String) authPrefs.get(i);
             Header challenge = challenges.get(id.toLowerCase(Locale.ENGLISH)); 
 
             if (challenge != null) {

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>

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
+ * Default implementation of {@link SetCookie}.
- * that the HTTP agent and the target server can exchange to maintain 
- * a session.
- * 
- * 
- * @version $Revision$
  *
  * @since 4.0
  */

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
+ * Default implementation of {@link SetCookie2}.
- * that the HTTP agent and the target server can exchange to maintain 
- * a session as specified by RFC2965.
- * 
  *
  * @since 4.0
  */

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
+ * 'Meta' cookie specification that picks up a cookie policy based on 
- * on the format of the cookie(s)
+ * the format of cookies sent with the HTTP response.
- * 
  *
  * @since 4.0
  */

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), 
+        	String[] patterns = null;
-                    params.getBooleanParameter(CookieSpecPNames.SINGLE_COOKIE_HEADER, false));
+        	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();
         }

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();
         }

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 
  */

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();
         }

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 
  */

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), 
+        	String[] patterns = null;
-                    params.getBooleanParameter(CookieSpecPNames.SINGLE_COOKIE_HEADER, false));
+        	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();
         }

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 4.0
- * @since 3.1
  */
 public class RFC2965Spec extends RFC2109Spec {
 

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), 
+        	String[] patterns = null;
-                    params.getBooleanParameter(CookieSpecPNames.SINGLE_COOKIE_HEADER, false));
+        	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();
         }

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>