From d715ace6293ce836385e41182382e47b5b49d549 Mon Sep 17 00:00:00 2001 From: Oleg Kalnichevski Date: Fri, 15 May 2009 20:32:30 +0000 Subject: [PATCH] Javadoc updates git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@775317 13f79535-47bb-0310-9956-ffa450edef68 --- .../java/org/apache/http/auth/AuthScheme.java | 18 ++------- .../apache/http/auth/AuthSchemeFactory.java | 9 ++++- .../apache/http/auth/AuthSchemeRegistry.java | 7 +--- .../org/apache/http/auth/Credentials.java | 7 ++-- .../org/apache/http/auth/NTCredentials.java | 7 ++-- .../org/apache/http/auth/NTUserPrincipal.java | 4 +- .../auth/UsernamePasswordCredentials.java | 7 +--- .../java/org/apache/http/auth/package.html | 4 +- .../apache/http/auth/params/AuthPNames.java | 9 +---- .../http/auth/params/AuthParamBean.java | 3 ++ .../apache/http/auth/params/AuthParams.java | 19 +++------ .../org/apache/http/auth/params/package.html | 2 +- .../http/client/params/HttpClientParams.java | 2 +- .../http/conn/params/ConnManagerParams.java | 5 +-- .../http/conn/params/ConnRouteParams.java | 4 +- .../apache/http/cookie/params/package.html | 3 +- .../apache/http/impl/auth/BasicScheme.java | 18 +++++---- .../http/impl/auth/BasicSchemeFactory.java | 3 +- .../apache/http/impl/auth/DigestScheme.java | 15 ++++--- .../http/impl/auth/DigestSchemeFactory.java | 3 +- .../org/apache/http/impl/auth/NTLMEngine.java | 3 -- .../org/apache/http/impl/auth/NTLMScheme.java | 10 ++++- .../apache/http/impl/auth/RFC2617Scheme.java | 5 +-- .../org/apache/http/impl/auth/package.html | 40 +++++++++++++++++++ .../impl/client/DefaultRequestDirector.java | 6 +++ 25 files changed, 122 insertions(+), 91 deletions(-) create mode 100644 httpclient/src/main/java/org/apache/http/impl/auth/package.html diff --git a/httpclient/src/main/java/org/apache/http/auth/AuthScheme.java b/httpclient/src/main/java/org/apache/http/auth/AuthScheme.java index 81f1cbfb5..9cb91a0c0 100644 --- a/httpclient/src/main/java/org/apache/http/auth/AuthScheme.java +++ b/httpclient/src/main/java/org/apache/http/auth/AuthScheme.java @@ -34,34 +34,24 @@ import org.apache.http.Header; import org.apache.http.HttpRequest; /** - *

* This interface represents an abstract challenge-response oriented * authentication scheme. - *

*

* An authentication scheme should be able to support the following * functions: *

- *

- *

- * Authentication schemes may ignore method name and URI parameters - * if they are not relevant for the given authentication mechanism - *

*

* Authentication schemes may be stateful involving a series of - * challenge-response exchanges - *

- * + * challenge-response exchanges. * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/auth/AuthSchemeFactory.java b/httpclient/src/main/java/org/apache/http/auth/AuthSchemeFactory.java index 59e59f6b4..73e08046e 100644 --- a/httpclient/src/main/java/org/apache/http/auth/AuthSchemeFactory.java +++ b/httpclient/src/main/java/org/apache/http/auth/AuthSchemeFactory.java @@ -34,12 +34,19 @@ package org.apache.http.auth; import org.apache.http.params.HttpParams; /** - * + * Factory for {@link AuthScheme} implementations. * * @since 4.0 */ public interface AuthSchemeFactory { + /** + * Creates an instance of {@link AuthScheme} using given HTTP parameters. + * + * @param params HTTP parameters. + * + * @return auth scheme. + */ AuthScheme newInstance(HttpParams params); } diff --git a/httpclient/src/main/java/org/apache/http/auth/AuthSchemeRegistry.java b/httpclient/src/main/java/org/apache/http/auth/AuthSchemeRegistry.java index bb8983865..314c79206 100644 --- a/httpclient/src/main/java/org/apache/http/auth/AuthSchemeRegistry.java +++ b/httpclient/src/main/java/org/apache/http/auth/AuthSchemeRegistry.java @@ -43,11 +43,8 @@ import org.apache.http.params.HttpParams; /** * Authentication scheme registry that can be used to obtain the corresponding - * authentication scheme implementation for a given type of authorization challenge. - * - * - * - * @version $Revision$ + * authentication scheme implementation for a given type of authorization challenge. + * * @since 4.0 */ @ThreadSafe diff --git a/httpclient/src/main/java/org/apache/http/auth/Credentials.java b/httpclient/src/main/java/org/apache/http/auth/Credentials.java index 62e9fb3ec..06da42ac3 100644 --- a/httpclient/src/main/java/org/apache/http/auth/Credentials.java +++ b/httpclient/src/main/java/org/apache/http/auth/Credentials.java @@ -33,10 +33,9 @@ package org.apache.http.auth; import java.security.Principal; /** - * User name and password based authentication credentials. - * - * - * @version $Revision$ $Date$ + * This interface represents a set of credentials consisting of a security + * principal and a secret (password) that can be used to establish user + * identity * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/auth/NTCredentials.java b/httpclient/src/main/java/org/apache/http/auth/NTCredentials.java index 88fdd2f3f..c022cab49 100644 --- a/httpclient/src/main/java/org/apache/http/auth/NTCredentials.java +++ b/httpclient/src/main/java/org/apache/http/auth/NTCredentials.java @@ -37,10 +37,11 @@ import net.jcip.annotations.Immutable; import org.apache.http.util.LangUtils; -/** {@link Credentials} specific to the Windows platform. - * +/** + * {@link Credentials} implementation for Microsoft Windows platforms that includes + * Windows specific attributes such as name of the domain the user belongs to. * - * @since 2.0 + * @since 4.0 */ @Immutable public class NTCredentials implements Credentials { diff --git a/httpclient/src/main/java/org/apache/http/auth/NTUserPrincipal.java b/httpclient/src/main/java/org/apache/http/auth/NTUserPrincipal.java index 872ca6318..80bb720fa 100644 --- a/httpclient/src/main/java/org/apache/http/auth/NTUserPrincipal.java +++ b/httpclient/src/main/java/org/apache/http/auth/NTUserPrincipal.java @@ -37,8 +37,8 @@ import net.jcip.annotations.Immutable; import org.apache.http.util.LangUtils; -/** NT (MS Windows specific) user principal used for HTTP authentication - * +/** + * Microsoft Windows specific user principal implementation. * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/auth/UsernamePasswordCredentials.java b/httpclient/src/main/java/org/apache/http/auth/UsernamePasswordCredentials.java index 3987bbd22..6a01cb96c 100644 --- a/httpclient/src/main/java/org/apache/http/auth/UsernamePasswordCredentials.java +++ b/httpclient/src/main/java/org/apache/http/auth/UsernamePasswordCredentials.java @@ -37,11 +37,8 @@ import net.jcip.annotations.Immutable; import org.apache.http.util.LangUtils; /** - * Username and password {@link Credentials} - * - * - * @version $Revision$ $Date$ - * + * Simple {@link Credentials} implementation based on a user name / password + * pair. * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/auth/package.html b/httpclient/src/main/java/org/apache/http/auth/package.html index 8bd6c1bfa..c1d6a3979 100644 --- a/httpclient/src/main/java/org/apache/http/auth/package.html +++ b/httpclient/src/main/java/org/apache/http/auth/package.html @@ -34,8 +34,6 @@ --> -The API for client-side HTTP authentication against a server, -commonly referred to as HttpAuth. - +The API for client-side HTTP authentication against a server. diff --git a/httpclient/src/main/java/org/apache/http/auth/params/AuthPNames.java b/httpclient/src/main/java/org/apache/http/auth/params/AuthPNames.java index 7b6837632..a6b6d7905 100644 --- a/httpclient/src/main/java/org/apache/http/auth/params/AuthPNames.java +++ b/httpclient/src/main/java/org/apache/http/auth/params/AuthPNames.java @@ -32,9 +32,7 @@ package org.apache.http.auth.params; /** - * Parameter names for HttpAuth. - * - * @version $Revision$ + * Parameter names for HTTP authentication classes. * * @since 4.0 */ @@ -45,11 +43,6 @@ public interface AuthPNames { * {@link org.apache.http.auth.Credentials}. *

* This parameter expects a value of type {@link String}. - * If not defined, then - * {@link org.apache.http.params.CoreProtocolPNames#HTTP_ELEMENT_CHARSET - * HttpProtocolParams.HTTP_ELEMENT_CHARSET} - * should be used. - *

*/ public static final String CREDENTIAL_CHARSET = "http.auth.credential-charset"; diff --git a/httpclient/src/main/java/org/apache/http/auth/params/AuthParamBean.java b/httpclient/src/main/java/org/apache/http/auth/params/AuthParamBean.java index a4e95fdab..f46137cf2 100644 --- a/httpclient/src/main/java/org/apache/http/auth/params/AuthParamBean.java +++ b/httpclient/src/main/java/org/apache/http/auth/params/AuthParamBean.java @@ -35,6 +35,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 authentication parameters + * using Java Beans conventions. * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/auth/params/AuthParams.java b/httpclient/src/main/java/org/apache/http/auth/params/AuthParams.java index ac011449a..f89df5b9f 100644 --- a/httpclient/src/main/java/org/apache/http/auth/params/AuthParams.java +++ b/httpclient/src/main/java/org/apache/http/auth/params/AuthParams.java @@ -37,11 +37,8 @@ import org.apache.http.params.HttpParams; import org.apache.http.protocol.HTTP; /** - * This class implements an adaptor around the {@link HttpParams} interface - * to simplify manipulation of the HTTP authentication specific parameters. - * - * - * @version $Revision$ + * An adaptor for manipulating HTTP authentication parameters + * in {@link HttpParams}. * * @since 4.0 * @@ -55,15 +52,11 @@ public final class AuthParams { } /** - * Obtains the charset for encoding - * {@link org.apache.http.auth.Credentials}. - * If not configured, - * {@link HTTP#DEFAULT_PROTOCOL_CHARSET HTTP.DEFAULT_PROTOCOL_CHARSET} - * is used instead. + * Obtains the charset for encoding + * {@link org.apache.http.auth.Credentials}.If not configured, + * {@link HTTP#DEFAULT_PROTOCOL_CHARSET}is used instead. * * @return The charset - * - * @see AuthPNames#CREDENTIAL_CHARSET */ public static String getCredentialCharset(final HttpParams params) { if (params == null) { @@ -71,8 +64,6 @@ public final class AuthParams { } String charset = (String) params.getParameter (AuthPNames.CREDENTIAL_CHARSET); - //@@@ TODO: inconsistent with JavaDoc in AuthPNames, - //@@@ TODO: check HTTP_ELEMENT_CHARSET first, or fix JavaDocs if (charset == null) { charset = HTTP.DEFAULT_PROTOCOL_CHARSET; } diff --git a/httpclient/src/main/java/org/apache/http/auth/params/package.html b/httpclient/src/main/java/org/apache/http/auth/params/package.html index 10386d4b4..8432071da 100644 --- a/httpclient/src/main/java/org/apache/http/auth/params/package.html +++ b/httpclient/src/main/java/org/apache/http/auth/params/package.html @@ -34,7 +34,7 @@ --> -Parameters for configuring HttpAuth. +Parameters for configuring HTTP authentication classes. 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 dea0493b6..ae001366b 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 @@ -35,7 +35,7 @@ import net.jcip.annotations.Immutable; import org.apache.http.params.HttpParams; /** - * An adaptor for accessing HTTP client parameters in {@link HttpParams}. + * An adaptor for manipulating HTTP client parameters in {@link HttpParams}. * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/conn/params/ConnManagerParams.java b/httpclient/src/main/java/org/apache/http/conn/params/ConnManagerParams.java index 35e0f5d7c..5b9d19b00 100644 --- a/httpclient/src/main/java/org/apache/http/conn/params/ConnManagerParams.java +++ b/httpclient/src/main/java/org/apache/http/conn/params/ConnManagerParams.java @@ -36,9 +36,8 @@ import org.apache.http.conn.routing.HttpRoute; import org.apache.http.params.HttpParams; /** - * This class represents a collection of HTTP protocol parameters applicable - * to client-side - * {@link org.apache.http.conn.ClientConnectionManager connection managers}. + * An adaptor for manipulating HTTP connection management + * parameters in {@link HttpParams}. * * @since 4.0 * diff --git a/httpclient/src/main/java/org/apache/http/conn/params/ConnRouteParams.java b/httpclient/src/main/java/org/apache/http/conn/params/ConnRouteParams.java index 2a3e3790e..4f1fdd5be 100644 --- a/httpclient/src/main/java/org/apache/http/conn/params/ConnRouteParams.java +++ b/httpclient/src/main/java/org/apache/http/conn/params/ConnRouteParams.java @@ -39,8 +39,8 @@ import org.apache.http.params.HttpParams; import org.apache.http.conn.routing.HttpRoute; /** - * An adaptor for accessing route related parameters in {@link HttpParams}. - * See {@link ConnRoutePNames} for parameter name definitions. + * An adaptor for manipulating HTTP routing parameters + * in {@link HttpParams}. * * @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 e50b0bd03..59f31ee71 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,6 @@ --> -Parameters for configuring HTTP state management -related classes. +Parameters for configuring HTTP state management classes. diff --git a/httpclient/src/main/java/org/apache/http/impl/auth/BasicScheme.java b/httpclient/src/main/java/org/apache/http/impl/auth/BasicScheme.java index 42ca1c30f..a2b6b12e7 100644 --- a/httpclient/src/main/java/org/apache/http/impl/auth/BasicScheme.java +++ b/httpclient/src/main/java/org/apache/http/impl/auth/BasicScheme.java @@ -45,14 +45,16 @@ import org.apache.http.util.CharArrayBuffer; import org.apache.http.util.EncodingUtils; /** - *

* Basic authentication scheme as defined in RFC 2617. - *

- * + *

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

* * @since 4.0 */ - @NotThreadSafe public class BasicScheme extends RFC2617Scheme { @@ -60,7 +62,7 @@ public class BasicScheme extends RFC2617Scheme { private boolean complete; /** - * Default constructor for the basic authetication scheme. + * Default constructor for the basic authentication scheme. */ public BasicScheme() { super(); @@ -113,10 +115,10 @@ public class BasicScheme extends RFC2617Scheme { /** * Produces basic authorization header for the given set of {@link Credentials}. * - * @param credentials The set of credentials to be used for athentication + * @param credentials The set of credentials to be used for authentication * @param request The request being authenticated - * @throws org.apache.http.auth.InvalidCredentialsException if authentication credentials - * are not valid or not applicable for this authentication scheme + * @throws InvalidCredentialsException if authentication credentials are not + * valid or not applicable for this authentication scheme * @throws AuthenticationException if authorization string cannot * be generated due to an authentication failure * diff --git a/httpclient/src/main/java/org/apache/http/impl/auth/BasicSchemeFactory.java b/httpclient/src/main/java/org/apache/http/impl/auth/BasicSchemeFactory.java index 874f9b322..e1677bf05 100644 --- a/httpclient/src/main/java/org/apache/http/impl/auth/BasicSchemeFactory.java +++ b/httpclient/src/main/java/org/apache/http/impl/auth/BasicSchemeFactory.java @@ -38,7 +38,8 @@ import org.apache.http.auth.AuthSchemeFactory; import org.apache.http.params.HttpParams; /** - * + * {@link AuthSchemeFactory} implementation that creates and initializes + * {@link BasicScheme} instances. * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/impl/auth/DigestScheme.java b/httpclient/src/main/java/org/apache/http/impl/auth/DigestScheme.java index c8f7baa20..7a879af82 100644 --- a/httpclient/src/main/java/org/apache/http/impl/auth/DigestScheme.java +++ b/httpclient/src/main/java/org/apache/http/impl/auth/DigestScheme.java @@ -51,24 +51,27 @@ import org.apache.http.util.CharArrayBuffer; import org.apache.http.util.EncodingUtils; /** - *

* Digest authentication scheme as defined in RFC 2617. * Both MD5 (default) and MD5-sess are supported. * Currently only qop=auth or no qop is supported. qop=auth-int * is unsupported. If auth and auth-int are provided, auth is * used. - *

*

* Credential charset is configured via the - * {@link org.apache.http.auth.params.AuthPNames#CREDENTIAL_CHARSET - * credential charset} parameter. + * {@link org.apache.http.auth.params.AuthPNames#CREDENTIAL_CHARSET} + * parameter of the HTTP request. + *

* Since the digest username is included as clear text in the generated * Authentication header, the charset of the username must be compatible * with the * {@link org.apache.http.params.CoreProtocolPNames#HTTP_ELEMENT_CHARSET * http element charset}. - *

- * + *

+ * 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/impl/auth/DigestSchemeFactory.java b/httpclient/src/main/java/org/apache/http/impl/auth/DigestSchemeFactory.java index 8f1a82484..0e3b4902f 100644 --- a/httpclient/src/main/java/org/apache/http/impl/auth/DigestSchemeFactory.java +++ b/httpclient/src/main/java/org/apache/http/impl/auth/DigestSchemeFactory.java @@ -38,7 +38,8 @@ import org.apache.http.auth.AuthSchemeFactory; import org.apache.http.params.HttpParams; /** - * + * {@link AuthSchemeFactory} implementation that creates and initializes + * {@link DigestScheme} instances. * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/impl/auth/NTLMEngine.java b/httpclient/src/main/java/org/apache/http/impl/auth/NTLMEngine.java index 860638bc2..88bdfb6e0 100644 --- a/httpclient/src/main/java/org/apache/http/impl/auth/NTLMEngine.java +++ b/httpclient/src/main/java/org/apache/http/impl/auth/NTLMEngine.java @@ -34,9 +34,6 @@ package org.apache.http.impl.auth; * Abstract NTLM authentication engine. The engine can be used to * generate Type1 messages and Type3 messages in response to a * Type2 challenge. - *

- * For details see this resource - * * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/impl/auth/NTLMScheme.java b/httpclient/src/main/java/org/apache/http/impl/auth/NTLMScheme.java index c0669d3cc..de3ae2c61 100644 --- a/httpclient/src/main/java/org/apache/http/impl/auth/NTLMScheme.java +++ b/httpclient/src/main/java/org/apache/http/impl/auth/NTLMScheme.java @@ -45,7 +45,15 @@ import org.apache.http.message.BufferedHeader; import org.apache.http.util.CharArrayBuffer; /** - * + * NTLM is a proprietary authentication scheme developed by Microsoft + * and optimized for Windows platforms. + *

+ * Please note that the NTLM scheme requires an external + * {@link NTLMEngine} implementation to function! + * For details please refer to + * + * this document. + * * @since 4.0 */ @NotThreadSafe diff --git a/httpclient/src/main/java/org/apache/http/impl/auth/RFC2617Scheme.java b/httpclient/src/main/java/org/apache/http/impl/auth/RFC2617Scheme.java index 64b04efb8..0a0e494c3 100644 --- a/httpclient/src/main/java/org/apache/http/impl/auth/RFC2617Scheme.java +++ b/httpclient/src/main/java/org/apache/http/impl/auth/RFC2617Scheme.java @@ -43,10 +43,9 @@ import org.apache.http.util.CharArrayBuffer; /** * Abstract authentication scheme class that lays foundation for all - * RFC 2617 compliant authetication schemes and provides capabilities common + * RFC 2617 compliant authentication schemes and provides capabilities common * to all authentication schemes defined in RFC 2617. * - * * @since 4.0 */ public abstract class RFC2617Scheme extends AuthSchemeBase { @@ -57,7 +56,7 @@ public abstract class RFC2617Scheme extends AuthSchemeBase { private Map params; /** - * Default constructor for RFC2617 compliant authetication schemes. + * Default constructor for RFC2617 compliant authentication schemes. */ public RFC2617Scheme() { super(); diff --git a/httpclient/src/main/java/org/apache/http/impl/auth/package.html b/httpclient/src/main/java/org/apache/http/impl/auth/package.html new file mode 100644 index 000000000..19dc7089c --- /dev/null +++ b/httpclient/src/main/java/org/apache/http/impl/auth/package.html @@ -0,0 +1,40 @@ + + + + + +Default implementations for interfaces in +{@link org.apache.http.auth org.apache.http.auth}. + + 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 a68eb0604..b9268f328 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 @@ -114,9 +114,15 @@ import org.apache.http.protocol.HttpRequestExecutor; *

  • {@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.ConnRoutePNames#FORCED_ROUTE}
    • + *
  • {@link org.apache.http.conn.params.ConnRoutePNames#LOCAL_ADDRESS}
    • + *
  • {@link org.apache.http.conn.params.ConnRoutePNames#DEFAULT_PROXY}
    • *
  • {@link org.apache.http.conn.params.ConnManagerPNames#TIMEOUT}
    • + *
  • {@link org.apache.http.conn.params.ConnManagerPNames#MAX_CONNECTIONS_PER_ROUTE}
    • + *
  • {@link org.apache.http.conn.params.ConnManagerPNames#MAX_TOTAL_CONNECTIONS}
    • *
  • {@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}
    • *
  • {@link org.apache.http.cookie.params.CookieSpecPNames#SINGLE_COOKIE_HEADER}
    • + *
  • {@link org.apache.http.auth.params.AuthPNames#CREDENTIAL_CHARSET}
    • *
  • {@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}