From a757cafadaf4e2dc001c96c96cba8a67dbc48417 Mon Sep 17 00:00:00 2001 From: Oleg Kalnichevski Date: Wed, 13 May 2009 18:13:35 +0000 Subject: [PATCH] Javadoc cleanups git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@774460 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/http/client/CookieStore.java | 10 ++--- .../http/client/params/ClientParamBean.java | 3 ++ .../http/client/params/CookiePolicy.java | 1 + .../http/client/params/HttpClientParams.java | 3 -- .../http/client/protocol/ClientContext.java | 29 +++++++++++--- .../client/protocol/RequestAddCookies.java | 13 ++++-- .../protocol/ResponseProcessCookies.java | 3 -- .../conn/params/ConnConnectionParamBean.java | 6 +-- .../conn/params/ConnManagerParamBean.java | 6 +-- .../http/conn/params/ConnRoutePNames.java | 2 +- .../http/conn/params/ConnRouteParamBean.java | 6 +-- .../java/org/apache/http/cookie/Cookie.java | 17 ++++---- .../http/cookie/CookieAttributeHandler.java | 2 +- .../http/cookie/CookieIdentityComparator.java | 3 -- .../org/apache/http/cookie/CookieOrigin.java | 3 +- .../apache/http/cookie/CookieSpecFactory.java | 9 ++++- .../org/apache/http/cookie/SetCookie.java | 3 +- .../org/apache/http/cookie/SetCookie2.java | 3 +- .../java/org/apache/http/cookie/package.html | 4 +- .../http/cookie/params/CookieSpecPNames.java | 24 +++++------ .../cookie/params/CookieSpecParamBean.java | 3 ++ .../apache/http/cookie/params/package.html | 4 +- .../client/AbstractAuthenticationHandler.java | 9 +++-- .../impl/client/DefaultRequestDirector.java | 15 +++++++ .../http/impl/cookie/BasicClientCookie.java | 7 +--- .../http/impl/cookie/BasicClientCookie2.java | 5 +-- .../http/impl/cookie/BestMatchSpec.java | 5 +-- .../impl/cookie/BestMatchSpecFactory.java | 27 +++++++++++-- .../impl/cookie/BrowserCompatSpecFactory.java | 22 ++++++++-- .../http/impl/cookie/NetscapeDraftSpec.java | 5 ++- .../impl/cookie/NetscapeDraftSpecFactory.java | 22 ++++++++-- .../apache/http/impl/cookie/RFC2109Spec.java | 8 +++- .../http/impl/cookie/RFC2109SpecFactory.java | 27 +++++++++++-- .../apache/http/impl/cookie/RFC2965Spec.java | 6 +-- .../http/impl/cookie/RFC2965SpecFactory.java | 27 +++++++++++-- .../org/apache/http/impl/cookie/package.html | 40 +++++++++++++++++++ 36 files changed, 274 insertions(+), 108 deletions(-) create mode 100644 httpclient/src/main/java/org/apache/http/impl/cookie/package.html diff --git a/httpclient/src/main/java/org/apache/http/client/CookieStore.java b/httpclient/src/main/java/org/apache/http/client/CookieStore.java index ca7ad41fd..7a74eada8 100644 --- 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 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. */ diff --git a/httpclient/src/main/java/org/apache/http/client/params/ClientParamBean.java b/httpclient/src/main/java/org/apache/http/client/params/ClientParamBean.java index 5d0a2ec4f..90abdba3b 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/client/params/CookiePolicy.java b/httpclient/src/main/java/org/apache/http/client/params/CookiePolicy.java index cc969fe0b..efdc9ad1c 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/client/params/HttpClientParams.java b/httpclient/src/main/java/org/apache/http/client/params/HttpClientParams.java index fc91c3337..dea0493b6 100644 --- 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 diff --git a/httpclient/src/main/java/org/apache/http/client/protocol/ClientContext.java b/httpclient/src/main/java/org/apache/http/client/protocol/ClientContext.java index c5dd50cba..00fb6c23e 100644 --- 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"; diff --git a/httpclient/src/main/java/org/apache/http/client/protocol/RequestAddCookies.java b/httpclient/src/main/java/org/apache/http/client/protocol/RequestAddCookies.java index 6b1df0c74..73b94f847 100644 --- 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 Cookie request headers. + *

+ * The following parameters can be used to customize the behavior of this + * class: + *

* * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/client/protocol/ResponseProcessCookies.java b/httpclient/src/main/java/org/apache/http/client/protocol/ResponseProcessCookies.java index d69d08a87..0b411868c 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/conn/params/ConnConnectionParamBean.java b/httpclient/src/main/java/org/apache/http/conn/params/ConnConnectionParamBean.java index 902091425..62f2c4df4 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/conn/params/ConnManagerParamBean.java b/httpclient/src/main/java/org/apache/http/conn/params/ConnManagerParamBean.java index 2d4eb2ac6..666dde677 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/conn/params/ConnRoutePNames.java b/httpclient/src/main/java/org/apache/http/conn/params/ConnRoutePNames.java index 2ee85ba29..f234ad789 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/conn/params/ConnRouteParamBean.java b/httpclient/src/main/java/org/apache/http/conn/params/ConnRouteParamBean.java index c2eaa85be..b8288a8b3 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/cookie/Cookie.java b/httpclient/src/main/java/org/apache/http/cookie/Cookie.java index 497736c83..66e5d54ed 100644 --- 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. */ diff --git a/httpclient/src/main/java/org/apache/http/cookie/CookieAttributeHandler.java b/httpclient/src/main/java/org/apache/http/cookie/CookieAttributeHandler.java index 798626b94..59ccaa2f9 100644 --- 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. * diff --git a/httpclient/src/main/java/org/apache/http/cookie/CookieIdentityComparator.java b/httpclient/src/main/java/org/apache/http/cookie/CookieIdentityComparator.java index 8a0bdf9a1..580739a7f 100644 --- 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. - * *

* Cookies are considered identical if their names are equal and * their domain attributes match ignoring case. - *

- * * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/cookie/CookieOrigin.java b/httpclient/src/main/java/org/apache/http/cookie/CookieOrigin.java index 1176ba631..2205565a5 100644 --- 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 diff --git a/httpclient/src/main/java/org/apache/http/cookie/CookieSpecFactory.java b/httpclient/src/main/java/org/apache/http/cookie/CookieSpecFactory.java index fa929dfee..38f6bd881 100644 --- 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); } diff --git a/httpclient/src/main/java/org/apache/http/cookie/SetCookie.java b/httpclient/src/main/java/org/apache/http/cookie/SetCookie.java index 518d0b7e2..877aacd95 100644 --- 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 SetCookie response header sent by the + * This interface represents a Set-Cookie 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 { diff --git a/httpclient/src/main/java/org/apache/http/cookie/SetCookie2.java b/httpclient/src/main/java/org/apache/http/cookie/SetCookie2.java index 09c0ecac2..c24273fa9 100644 --- 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 SetCookie2 response header sent by the + * This interface represents a Set-Cookie2 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 { diff --git a/httpclient/src/main/java/org/apache/http/cookie/package.html b/httpclient/src/main/java/org/apache/http/cookie/package.html index bce286e3a..c7e8a0a8b 100644 --- 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 @@ --> -The API for client-side state management via cookies, -commonly referred to as HttpCookie. - +The API for client-side state management via cookies. diff --git a/httpclient/src/main/java/org/apache/http/cookie/params/CookieSpecPNames.java b/httpclient/src/main/java/org/apache/http/cookie/params/CookieSpecPNames.java index 6cd6eaf3c..ad100ad76 100644 --- 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 + * expires attribute. Only required for compatibility + * with non-compliant servers that still use expires + * defined in the Netscape draft instead of the standard + * max-age attribute. *

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

*/ 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 + * Cookie request header. Otherwise, each cookie is formatted + * as a separate Cookie header. *

* This parameter expects a value of type {@link Boolean}. *

diff --git a/httpclient/src/main/java/org/apache/http/cookie/params/CookieSpecParamBean.java b/httpclient/src/main/java/org/apache/http/cookie/params/CookieSpecParamBean.java index e1ea6712f..9d55f1687 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/cookie/params/package.html b/httpclient/src/main/java/org/apache/http/cookie/params/package.html index 2fe1113cd..e50b0bd03 100644 --- 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 @@ --> -Parameters for configuring HttpCookie. - +Parameters for configuring HTTP state management +related classes. diff --git a/httpclient/src/main/java/org/apache/http/impl/client/AbstractAuthenticationHandler.java b/httpclient/src/main/java/org/apache/http/impl/client/AbstractAuthenticationHandler.java index cc06ae650..e187c5989 100644 --- 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 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 authPrefs = (Collection) 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) { diff --git a/httpclient/src/main/java/org/apache/http/impl/client/DefaultRequestDirector.java b/httpclient/src/main/java/org/apache/http/impl/client/DefaultRequestDirector.java index 6eb7b7e41..a68eb0604 100644 --- 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: *
    *
  • {@link org.apache.http.params.CoreProtocolPNames#PROTOCOL_VERSION}
    • + *
  • {@link org.apache.http.params.CoreProtocolPNames#STRICT_TRANSFER_ENCODING}
    • + *
  • {@link org.apache.http.params.CoreProtocolPNames#HTTP_ELEMENT_CHARSET}
    • + *
  • {@link org.apache.http.params.CoreProtocolPNames#USE_EXPECT_CONTINUE}
    • + *
  • {@link org.apache.http.params.CoreProtocolPNames#WAIT_FOR_CONTINUE}
    • + *
  • {@link org.apache.http.params.CoreProtocolPNames#USER_AGENT}
    • + *
  • {@link org.apache.http.params.CoreConnectionPNames#SOCKET_BUFFER_SIZE}
    • + *
  • {@link org.apache.http.params.CoreConnectionPNames#MAX_LINE_LENGTH}
    • + *
  • {@link org.apache.http.params.CoreConnectionPNames#MAX_HEADER_COUNT}
    • + *
  • {@link org.apache.http.params.CoreConnectionPNames#SO_TIMEOUT}
    • + *
  • {@link org.apache.http.params.CoreConnectionPNames#SO_LINGER}
    • + *
  • {@link org.apache.http.params.CoreConnectionPNames#TCP_NODELAY}
    • + *
  • {@link org.apache.http.params.CoreConnectionPNames#CONNECTION_TIMEOUT}
    • *
  • {@link org.apache.http.params.CoreConnectionPNames#STALE_CONNECTION_CHECK}
    • *
  • {@link org.apache.http.conn.params.ConnManagerPNames#TIMEOUT}
    • + *
  • {@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}
    • + *
  • {@link org.apache.http.cookie.params.CookieSpecPNames#SINGLE_COOKIE_HEADER}
    • + *
  • {@link org.apache.http.client.params.ClientPNames#COOKIE_POLICY}
    • *
  • {@link org.apache.http.client.params.ClientPNames#VIRTUAL_HOST}
    • *
  • {@link org.apache.http.client.params.ClientPNames#MAX_REDIRECTS}
    • *
  • {@link org.apache.http.client.params.ClientPNames#DEFAULT_HOST}
    • diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/BasicClientCookie.java b/httpclient/src/main/java/org/apache/http/impl/cookie/BasicClientCookie.java index 775b270c8..43373f6a7 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/BasicClientCookie2.java b/httpclient/src/main/java/org/apache/http/impl/cookie/BasicClientCookie2.java index 6385c1617..805ec7099 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpec.java b/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpec.java index 089a4cc42..298de6e86 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpecFactory.java b/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpecFactory.java index 3ba6c246b..d4f54fbc2 100644 --- 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. + *

    + * The following parameters can be used to customize the behavior of this + * class: + *

      + *
    • {@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}
      • + *
    • {@link org.apache.http.cookie.params.CookieSpecPNames#SINGLE_COOKIE_HEADER}
      • + *
    * * @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(); } diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpecFactory.java b/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpecFactory.java index 00d5b8819..ab94a69b4 100644 --- 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. + *

    + * The following parameters can be used to customize the behavior of this + * class: + *

      + *
    • {@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}
      • + *
    * * @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(); } diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/NetscapeDraftSpec.java b/httpclient/src/main/java/org/apache/http/impl/cookie/NetscapeDraftSpec.java index bc5355b7d..ab7e292db 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/NetscapeDraftSpecFactory.java b/httpclient/src/main/java/org/apache/http/impl/cookie/NetscapeDraftSpecFactory.java index 5df9ecec1..2af1c497f 100644 --- 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. + *

    + * The following parameters can be used to customize the behavior of this + * class: + *

      + *
    • {@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}
      • + *
    * * @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(); } diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2109Spec.java b/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2109Spec.java index 9a82e2af2..f79e04f1c 100644 --- 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 */ diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2109SpecFactory.java b/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2109SpecFactory.java index cd4d88aae..d3aa7f87e 100644 --- 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. + *

    + * The following parameters can be used to customize the behavior of this + * class: + *

      + *
    • {@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}
      • + *
    • {@link org.apache.http.cookie.params.CookieSpecPNames#SINGLE_COOKIE_HEADER}
      • + *
    * * @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(); } diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2965Spec.java b/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2965Spec.java index ef686fb7b..af763bba9 100644 --- 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; /** - *

    RFC 2965 specific cookie management functions.

    - * + * RFC 2965 compliant {@link CookieSpec} implementation. * - * @since 3.1 + * @since 4.0 */ public class RFC2965Spec extends RFC2109Spec { diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2965SpecFactory.java b/httpclient/src/main/java/org/apache/http/impl/cookie/RFC2965SpecFactory.java index bd16986a5..cca2e272a 100644 --- 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. + *

    + * The following parameters can be used to customize the behavior of this + * class: + *

      + *
    • {@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}
      • + *
    • {@link org.apache.http.cookie.params.CookieSpecPNames#SINGLE_COOKIE_HEADER}
      • + *
    * * @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(); } diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/package.html b/httpclient/src/main/java/org/apache/http/impl/cookie/package.html new file mode 100644 index 000000000..8e56d4a6a --- /dev/null +++ b/httpclient/src/main/java/org/apache/http/impl/cookie/package.html @@ -0,0 +1,40 @@ + + + + + +Default implementations for interfaces in +{@link org.apache.http.cookie org.apache.http.cookie}. + +