Apache/httpcomponents-client
1
0
Fork 0
mirror of https://github.com/apache/httpcomponents-client.git synced 2025-02-13 13:35:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Javadoc updates

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@775317 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Oleg Kalnichevski 2009-05-15 20:32:30 +00:00
parent a757cafada
commit d715ace629
25 changed files with 122 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
httpclient/src/main/java/org/apache/http/auth/AuthScheme.java
View File

@ -34,34 +34,24 @@
import org.apache.http.HttpRequest; import org.apache.http.HttpRequest;
/** /**
* <p>
* This interface represents an abstract challenge-response oriented * This interface represents an abstract challenge-response oriented
* authentication scheme. * authentication scheme.
* </p>
* <p> * <p>
* An authentication scheme should be able to support the following * An authentication scheme should be able to support the following
* functions: * functions:
* <ul> * <ul>
* <li>Parse and process the challenge sent by the targer server * <li>Parse and process the challenge sent by the target server
* in response to request for a protected resource * in response to request for a protected resource
* <li>Provide its textual designation * <li>Provide its textual designation
* <li>Provide its parameters, if available * <li>Provide its parameters, if available
* <li>Provide the realm this authentication scheme is applicable to, * <li>Provide the realm this authentication scheme is applicable to,
* if available * if available
* <li>Generate authorization string for the given set of credentials, * <li>Generate authorization string for the given set of credentials
* request method and URI as specificed in the HTTP request line * and the HTTP request in response to the authorization challenge.
* in response to the actual authorization challenge
* </ul> * </ul>
* </p>
* <p>
* Authentication schemes may ignore method name and URI parameters
* if they are not relevant for the given authentication mechanism
* </p>
* <p> * <p>
* Authentication schemes may be stateful involving a series of * Authentication schemes may be stateful involving a series of
* challenge-response exchanges * challenge-response exchanges.
* </p>
*
* *
* @since 4.0 * @since 4.0
*/ */

9
httpclient/src/main/java/org/apache/http/auth/AuthSchemeFactory.java
View File

@ -34,12 +34,19 @@
import org.apache.http.params.HttpParams; import org.apache.http.params.HttpParams;
/** /**
* * Factory for {@link AuthScheme} implementations.
* *
* @since 4.0 * @since 4.0
*/ */
public interface AuthSchemeFactory { public interface AuthSchemeFactory {
/**
* Creates an instance of {@link AuthScheme} using given HTTP parameters.
*
* @param params HTTP parameters.
*
* @return auth scheme.
*/
AuthScheme newInstance(HttpParams params); AuthScheme newInstance(HttpParams params);
} }

3
httpclient/src/main/java/org/apache/http/auth/AuthSchemeRegistry.java
View File

@ -45,9 +45,6 @@
* Authentication scheme registry that can be used to obtain the corresponding * Authentication scheme registry that can be used to obtain the corresponding
* authentication scheme implementation for a given type of authorization challenge. * authentication scheme implementation for a given type of authorization challenge.
* *
*
*
* @version $Revision$
* @since 4.0 * @since 4.0
*/ */
@ThreadSafe @ThreadSafe

7
httpclient/src/main/java/org/apache/http/auth/Credentials.java
View File

@ -33,10 +33,9 @@
import java.security.Principal; import java.security.Principal;
/** /**
* User name and password based authentication credentials. * This interface represents a set of credentials consisting of a security
* * principal and a secret (password) that can be used to establish user
* * identity
* @version $Revision$ $Date$
* *
* @since 4.0 * @since 4.0
*/ */

7
httpclient/src/main/java/org/apache/http/auth/NTCredentials.java
View File

@ -37,10 +37,11 @@
import org.apache.http.util.LangUtils; 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 4.0
* @since 2.0
*/ */
@Immutable @Immutable
public class NTCredentials implements Credentials { public class NTCredentials implements Credentials {

4
httpclient/src/main/java/org/apache/http/auth/NTUserPrincipal.java
View File

@ -37,8 +37,8 @@
import org.apache.http.util.LangUtils; 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 * @since 4.0
*/ */

7
httpclient/src/main/java/org/apache/http/auth/UsernamePasswordCredentials.java
View File

@ -37,11 +37,8 @@
import org.apache.http.util.LangUtils; import org.apache.http.util.LangUtils;
/** /**
* Username and password {@link Credentials} * Simple {@link Credentials} implementation based on a user name / password
* * pair.
*
* @version $Revision$ $Date$
*
* *
* @since 4.0 * @since 4.0
*/ */

4
httpclient/src/main/java/org/apache/http/auth/package.html
View File

@ -34,8 +34,6 @@
--> -->
</head> </head>
<body> <body>
The API for client-side HTTP authentication against a server, The API for client-side HTTP authentication against a server.
commonly referred to as <i>HttpAuth</i>.
</body> </body>
</html> </html>

9
httpclient/src/main/java/org/apache/http/auth/params/AuthPNames.java
View File

@ -32,9 +32,7 @@
package org.apache.http.auth.params; package org.apache.http.auth.params;
/** /**
* Parameter names for HttpAuth. * Parameter names for HTTP authentication classes.
*
* @version $Revision$
* *
* @since 4.0 * @since 4.0
*/ */
@ -45,11 +43,6 @@ public interface AuthPNames {
* {@link org.apache.http.auth.Credentials}. * {@link org.apache.http.auth.Credentials}.
* <p> * <p>
* This parameter expects a value of type {@link String}. * 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.
* </p>
*/ */
public static final String CREDENTIAL_CHARSET = "http.auth.credential-charset"; public static final String CREDENTIAL_CHARSET = "http.auth.credential-charset";

3
httpclient/src/main/java/org/apache/http/auth/params/AuthParamBean.java
View File

@ -35,6 +35,9 @@
import org.apache.http.params.HttpParams; 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 * @since 4.0
*/ */

17
httpclient/src/main/java/org/apache/http/auth/params/AuthParams.java
View File

@ -37,11 +37,8 @@
import org.apache.http.protocol.HTTP; import org.apache.http.protocol.HTTP;
/** /**
* This class implements an adaptor around the {@link HttpParams} interface * An adaptor for manipulating HTTP authentication parameters
* to simplify manipulation of the HTTP authentication specific parameters. * in {@link HttpParams}.
*
*
* @version $Revision$
* *
* @since 4.0 * @since 4.0
* *
@ -56,14 +53,10 @@ private AuthParams() {
/** /**
* Obtains the charset for encoding * Obtains the charset for encoding
* {@link org.apache.http.auth.Credentials}. * {@link org.apache.http.auth.Credentials}.If not configured,
* If not configured, * {@link HTTP#DEFAULT_PROTOCOL_CHARSET}is used instead.
* {@link HTTP#DEFAULT_PROTOCOL_CHARSET HTTP.DEFAULT_PROTOCOL_CHARSET}
* is used instead.
* *
* @return The charset * @return The charset
*
* @see AuthPNames#CREDENTIAL_CHARSET
*/ */
public static String getCredentialCharset(final HttpParams params) { public static String getCredentialCharset(final HttpParams params) {
if (params == null) { if (params == null) {
@ -71,8 +64,6 @@ public static String getCredentialCharset(final HttpParams params) {
} }
String charset = (String) params.getParameter String charset = (String) params.getParameter
(AuthPNames.CREDENTIAL_CHARSET); (AuthPNames.CREDENTIAL_CHARSET);
//@@@ TODO: inconsistent with JavaDoc in AuthPNames,
//@@@ TODO: check HTTP_ELEMENT_CHARSET first, or fix JavaDocs
if (charset == null) { if (charset == null) {
charset = HTTP.DEFAULT_PROTOCOL_CHARSET; charset = HTTP.DEFAULT_PROTOCOL_CHARSET;
} }

2
httpclient/src/main/java/org/apache/http/auth/params/package.html
View File

@ -34,7 +34,7 @@
--> -->
</head> </head>
<body> <body>
Parameters for configuring <i>HttpAuth</i>. Parameters for configuring HTTP authentication classes.
</body> </body>
</html> </html>

2
httpclient/src/main/java/org/apache/http/client/params/HttpClientParams.java
View File

@ -35,7 +35,7 @@
import org.apache.http.params.HttpParams; 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 * @since 4.0
*/ */

5
httpclient/src/main/java/org/apache/http/conn/params/ConnManagerParams.java
View File

@ -36,9 +36,8 @@
import org.apache.http.params.HttpParams; import org.apache.http.params.HttpParams;
/** /**
* This class represents a collection of HTTP protocol parameters applicable * An adaptor for manipulating HTTP connection management
* to client-side * parameters in {@link HttpParams}.
* {@link org.apache.http.conn.ClientConnectionManager connection managers}.
* *
* @since 4.0 * @since 4.0
* *

4
httpclient/src/main/java/org/apache/http/conn/params/ConnRouteParams.java
View File

@ -39,8 +39,8 @@
import org.apache.http.conn.routing.HttpRoute; import org.apache.http.conn.routing.HttpRoute;
/** /**
* An adaptor for accessing route related parameters in {@link HttpParams}. * An adaptor for manipulating HTTP routing parameters
* See {@link ConnRoutePNames} for parameter name definitions. * in {@link HttpParams}.
* *
* @since 4.0 * @since 4.0
*/ */

3
httpclient/src/main/java/org/apache/http/cookie/params/package.html
View File

@ -34,7 +34,6 @@
--> -->
</head> </head>
<body> <body>
Parameters for configuring HTTP state management Parameters for configuring HTTP state management classes.
related classes.
</body> </body>
</html> </html>

18
httpclient/src/main/java/org/apache/http/impl/auth/BasicScheme.java
View File

@ -45,14 +45,16 @@
import org.apache.http.util.EncodingUtils; import org.apache.http.util.EncodingUtils;
/** /**
* <p>
* Basic authentication scheme as defined in RFC 2617. * Basic authentication scheme as defined in RFC 2617.
* </p> * <p>
* * The following parameters can be used to customize the behavior of this
* class:
* <ul>
* <li>{@link org.apache.http.auth.params.AuthPNames#CREDENTIAL_CHARSET}</li>
* </ul>
* *
* @since 4.0 * @since 4.0
*/ */
@NotThreadSafe @NotThreadSafe
public class BasicScheme extends RFC2617Scheme { public class BasicScheme extends RFC2617Scheme {
@ -60,7 +62,7 @@ public class BasicScheme extends RFC2617Scheme {
private boolean complete; private boolean complete;
/** /**
* Default constructor for the basic authetication scheme. * Default constructor for the basic authentication scheme.
*/ */
public BasicScheme() { public BasicScheme() {
super(); super();
@ -113,10 +115,10 @@ public boolean isConnectionBased() {
/** /**
* Produces basic authorization header for the given set of {@link Credentials}. * 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 * @param request The request being authenticated
* @throws org.apache.http.auth.InvalidCredentialsException if authentication credentials * @throws InvalidCredentialsException if authentication credentials are not
* are not valid or not applicable for this authentication scheme * valid or not applicable for this authentication scheme
* @throws AuthenticationException if authorization string cannot * @throws AuthenticationException if authorization string cannot
* be generated due to an authentication failure * be generated due to an authentication failure
* *

3
httpclient/src/main/java/org/apache/http/impl/auth/BasicSchemeFactory.java
View File

@ -38,7 +38,8 @@
import org.apache.http.params.HttpParams; import org.apache.http.params.HttpParams;
/** /**
* * {@link AuthSchemeFactory} implementation that creates and initializes
* {@link BasicScheme} instances.
* *
* @since 4.0 * @since 4.0
*/ */

15
httpclient/src/main/java/org/apache/http/impl/auth/DigestScheme.java
View File

@ -51,24 +51,27 @@
import org.apache.http.util.EncodingUtils; import org.apache.http.util.EncodingUtils;
/** /**
* <p>
* Digest authentication scheme as defined in RFC 2617. * Digest authentication scheme as defined in RFC 2617.
* Both MD5 (default) and MD5-sess are supported. * Both MD5 (default) and MD5-sess are supported.
* Currently only qop=auth or no qop is supported. qop=auth-int * Currently only qop=auth or no qop is supported. qop=auth-int
* is unsupported. If auth and auth-int are provided, auth is * is unsupported. If auth and auth-int are provided, auth is
* used. * used.
* </p>
* <p> * <p>
* Credential charset is configured via the * Credential charset is configured via the
* {@link org.apache.http.auth.params.AuthPNames#CREDENTIAL_CHARSET * {@link org.apache.http.auth.params.AuthPNames#CREDENTIAL_CHARSET}
* credential charset} parameter. * parameter of the HTTP request.
* <p>
* Since the digest username is included as clear text in the generated * Since the digest username is included as clear text in the generated
* Authentication header, the charset of the username must be compatible * Authentication header, the charset of the username must be compatible
* with the * with the
* {@link org.apache.http.params.CoreProtocolPNames#HTTP_ELEMENT_CHARSET * {@link org.apache.http.params.CoreProtocolPNames#HTTP_ELEMENT_CHARSET
* http element charset}. * http element charset}.
* </p> * <p>
* * The following parameters can be used to customize the behavior of this
* class:
* <ul>
* <li>{@link org.apache.http.auth.params.AuthPNames#CREDENTIAL_CHARSET}</li>
* </ul>
* *
* @since 4.0 * @since 4.0
*/ */

3
httpclient/src/main/java/org/apache/http/impl/auth/DigestSchemeFactory.java
View File

@ -38,7 +38,8 @@
import org.apache.http.params.HttpParams; import org.apache.http.params.HttpParams;
/** /**
* * {@link AuthSchemeFactory} implementation that creates and initializes
* {@link DigestScheme} instances.
* *
* @since 4.0 * @since 4.0
*/ */

3
httpclient/src/main/java/org/apache/http/impl/auth/NTLMEngine.java
View File

@ -34,9 +34,6 @@
* Abstract NTLM authentication engine. The engine can be used to * Abstract NTLM authentication engine. The engine can be used to
* generate Type1 messages and Type3 messages in response to a * generate Type1 messages and Type3 messages in response to a
* Type2 challenge. * Type2 challenge.
* <p/>
* For details see <a href="http://davenport.sourceforge.net/ntlm.html">this resource</a>
*
* *
* @since 4.0 * @since 4.0
*/ */

8
httpclient/src/main/java/org/apache/http/impl/auth/NTLMScheme.java
View File

@ -45,6 +45,14 @@
import org.apache.http.util.CharArrayBuffer; import org.apache.http.util.CharArrayBuffer;
/** /**
* NTLM is a proprietary authentication scheme developed by Microsoft
* and optimized for Windows platforms.
* <p>
* Please note that the NTLM scheme requires an external
* {@link NTLMEngine} implementation to function!
* For details please refer to
* <a href="http://hc.apache.org/httpcomponents-client/ntlm.html">
* this document</a>.
* *
* @since 4.0 * @since 4.0
*/ */

5
httpclient/src/main/java/org/apache/http/impl/auth/RFC2617Scheme.java
View File

@ -43,10 +43,9 @@
/** /**
* Abstract authentication scheme class that lays foundation for all * 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. * to all authentication schemes defined in RFC 2617.
* *
*
* @since 4.0 * @since 4.0
*/ */
public abstract class RFC2617Scheme extends AuthSchemeBase { public abstract class RFC2617Scheme extends AuthSchemeBase {
@ -57,7 +56,7 @@ public abstract class RFC2617Scheme extends AuthSchemeBase {
private Map<String, String> params; private Map<String, String> params;
/** /**
* Default constructor for RFC2617 compliant authetication schemes. * Default constructor for RFC2617 compliant authentication schemes.
*/ */
public RFC2617Scheme() { public RFC2617Scheme() {
super(); super();

40
httpclient/src/main/java/org/apache/http/impl/auth/package.html Normal file
View File

@ -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.auth org.apache.http.auth}.
</body>
</html>

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

@ -114,9 +114,15 @@
* <li>{@link org.apache.http.params.CoreConnectionPNames#TCP_NODELAY}</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#CONNECTION_TIMEOUT}</li>
* <li>{@link org.apache.http.params.CoreConnectionPNames#STALE_CONNECTION_CHECK}</li> * <li>{@link org.apache.http.params.CoreConnectionPNames#STALE_CONNECTION_CHECK}</li>
* <li>{@link org.apache.http.conn.params.ConnRoutePNames#FORCED_ROUTE}</li>
* <li>{@link org.apache.http.conn.params.ConnRoutePNames#LOCAL_ADDRESS}</li>
* <li>{@link org.apache.http.conn.params.ConnRoutePNames#DEFAULT_PROXY}</li>
* <li>{@link org.apache.http.conn.params.ConnManagerPNames#TIMEOUT}</li> * <li>{@link org.apache.http.conn.params.ConnManagerPNames#TIMEOUT}</li>
* <li>{@link org.apache.http.conn.params.ConnManagerPNames#MAX_CONNECTIONS_PER_ROUTE}</li>
* <li>{@link org.apache.http.conn.params.ConnManagerPNames#MAX_TOTAL_CONNECTIONS}</li>
* <li>{@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}</li> * <li>{@link org.apache.http.cookie.params.CookieSpecPNames#DATE_PATTERNS}</li>
* <li>{@link org.apache.http.cookie.params.CookieSpecPNames#SINGLE_COOKIE_HEADER}</li> * <li>{@link org.apache.http.cookie.params.CookieSpecPNames#SINGLE_COOKIE_HEADER}</li>
* <li>{@link org.apache.http.auth.params.AuthPNames#CREDENTIAL_CHARSET}</li>
* <li>{@link org.apache.http.client.params.ClientPNames#COOKIE_POLICY}</li> * <li>{@link org.apache.http.client.params.ClientPNames#COOKIE_POLICY}</li>
* <li>{@link org.apache.http.client.params.ClientPNames#VIRTUAL_HOST}</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#MAX_REDIRECTS}</li>