From 4f04500b22531e1fed30fb47569274f9279b3ca3 Mon Sep 17 00:00:00 2001 From: Oleg Kalnichevski Date: Thu, 4 Jun 2009 18:17:38 +0000 Subject: [PATCH] Javadoc cleanups; fixed some binary incompatibilities with 4.0-beta1 git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@781821 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/http/client/HttpClient.java | 5 ++ .../apache/http/client/UserTokenHandler.java | 5 +- .../http/client/params/ClientPNames.java | 3 +- .../http/client/protocol/ClientContext.java | 4 + .../http/impl/client/AbstractHttpClient.java | 31 +++++-- .../http/impl/client/DefaultHttpClient.java | 86 ++++++++++++++----- .../impl/client/DefaultRedirectHandler.java | 6 -- .../impl/client/DefaultRequestDirector.java | 13 +-- .../impl/client/DefaultUserTokenHandler.java | 10 +++ .../http/impl/client/RoutedRequest.java | 10 +-- .../http/impl/cookie/BestMatchSpec.java | 6 +- .../http/impl/cookie/BrowserCompatSpec.java | 27 ++++-- 12 files changed, 146 insertions(+), 60 deletions(-) diff --git a/httpclient/src/main/java/org/apache/http/client/HttpClient.java b/httpclient/src/main/java/org/apache/http/client/HttpClient.java index 00674e716..6dae215e7 100644 --- a/httpclient/src/main/java/org/apache/http/client/HttpClient.java +++ b/httpclient/src/main/java/org/apache/http/client/HttpClient.java @@ -96,6 +96,11 @@ import org.apache.http.protocol.HttpContext; * instream.close(); * * } + * + * // When HttpClient instance is no longer needed, + * // shut down the connection manager to ensure + * // immediate deallocation of all system resources + * httpclient.getConnectionManager().shutdown(); * } * * diff --git a/httpclient/src/main/java/org/apache/http/client/UserTokenHandler.java b/httpclient/src/main/java/org/apache/http/client/UserTokenHandler.java index c1a09a74b..64ef8b47b 100644 --- a/httpclient/src/main/java/org/apache/http/client/UserTokenHandler.java +++ b/httpclient/src/main/java/org/apache/http/client/UserTokenHandler.java @@ -40,9 +40,8 @@ import org.apache.http.protocol.HttpContext; * null if the context does not contain any resources or details * specific to the current user. *

- * The user token will be used to ensure that user specific resouces will not - * shared with or reused by other users. - * + * The user token will be used to ensure that user specific resources will not + * be shared with or reused by other users. * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/client/params/ClientPNames.java b/httpclient/src/main/java/org/apache/http/client/params/ClientPNames.java index 36ecb35df..a56a26e1d 100644 --- a/httpclient/src/main/java/org/apache/http/client/params/ClientPNames.java +++ b/httpclient/src/main/java/org/apache/http/client/params/ClientPNames.java @@ -60,7 +60,8 @@ public interface ClientPNames { public static final String HANDLE_REDIRECTS = "http.protocol.handle-redirects"; /** - * Defines whether relative redirects should be rejected. + * Defines whether relative redirects should be rejected. HTTP specification + * requires the location value be an absolute URI. *

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

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 8c0a336ba..7d4e8b761 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 @@ -97,6 +97,10 @@ public interface ClientContext { */ public static final String AUTH_SCHEME_PREF = "http.auth.scheme-pref"; + /** + * Attribute name of a {@link java.lang.Object} object that represents + * the actual user identity such as user {@link java.security.Principal}. + */ public static final String USER_TOKEN = "http.user-token"; } diff --git a/httpclient/src/main/java/org/apache/http/impl/client/AbstractHttpClient.java b/httpclient/src/main/java/org/apache/http/impl/client/AbstractHttpClient.java index c49ccfe3b..e5b890d07 100644 --- a/httpclient/src/main/java/org/apache/http/impl/client/AbstractHttpClient.java +++ b/httpclient/src/main/java/org/apache/http/impl/client/AbstractHttpClient.java @@ -71,10 +71,14 @@ import org.apache.http.protocol.HttpProcessor; import org.apache.http.protocol.HttpRequestExecutor; /** - * Base class for {@link HttpClient} implementations. - *

- * This class maintains a number of objects used during HTTP request execution - * and provides a number of factory methods to instantiate those objects: + * Base class for {@link HttpClient} implementations. This class acts as + * a facade to a number of special purpose handler or strategy + * implementations responsible for handling of a particular aspect of + * the HTTP protocol such as redirect or authentication handling or + * making decision about connection persistence and keep alive duration. + * This enables the users to selectively replace default implementation + * of those aspects with custom, application specific ones. This class + * also provides factory methods to instantiate those objects: *

+ *

+ * This class also maintains a list of protocol interceptors intended + * for processing outgoing requests and incoming responses and provides + * methods for managing those interceptors. New protocol interceptors can be + * introduced to the protocol processor chain or removed from it if needed. + * Internally protocol interceptors are stored in a simple + * {@link java.util.ArrayList}. They are executed in the same natural order + * as they are added to the list. + *

+ * AbstractHttpClient is thread safe. It is recommended that the same + * instance of this class is reused for multiple request executions. + * When an instance of DefaultHttpClient is no longer needed and is about + * to go out of scope the connection manager associated with it must be + * shut down by calling {@link ClientConnectionManager#shutdown()}! * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/impl/client/DefaultHttpClient.java b/httpclient/src/main/java/org/apache/http/impl/client/DefaultHttpClient.java index 7e086b6ca..784983d4b 100644 --- a/httpclient/src/main/java/org/apache/http/impl/client/DefaultHttpClient.java +++ b/httpclient/src/main/java/org/apache/http/impl/client/DefaultHttpClient.java @@ -86,16 +86,73 @@ import org.apache.http.protocol.RequestTargetHost; import org.apache.http.protocol.RequestUserAgent; import org.apache.http.util.VersionInfo; - - /** - * Default implementation of an HTTP client. - *
- * This class replaces HttpClient in HttpClient 3. - * - * - * - * @version $Revision$ + * Default implementation of {@link AbstractHttpClient}. + *

+ * This class creates an instance of {@link SingleClientConnManager} + * for connection management if not explicitly set. + *

+ * This class creates the following chain of protocol interceptors per + * default: + *

+ *

+ * This class sets up the following parameters if not explicitly set: + *

+ *

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

* * @since 4.0 */ @@ -126,17 +183,6 @@ public class DefaultHttpClient extends AbstractHttpClient { } - /** - * Creates a new BasicHttpParams object, and sets up the following: - * - */ @Override protected HttpParams createHttpParams() { HttpParams params = new BasicHttpParams(); diff --git a/httpclient/src/main/java/org/apache/http/impl/client/DefaultRedirectHandler.java b/httpclient/src/main/java/org/apache/http/impl/client/DefaultRedirectHandler.java index 9b6efb346..039dcfe71 100644 --- a/httpclient/src/main/java/org/apache/http/impl/client/DefaultRedirectHandler.java +++ b/httpclient/src/main/java/org/apache/http/impl/client/DefaultRedirectHandler.java @@ -52,14 +52,8 @@ import org.apache.http.params.HttpParams; import org.apache.http.protocol.HttpContext; import org.apache.http.protocol.ExecutionContext; - /** * Default implementation of {@link RedirectHandler}. - * - * - * - * - * @version $Revision$ * * @since 4.0 */ 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 3083a33a7..91739ad2f 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 @@ -533,12 +533,15 @@ public class DefaultRequestDirector implements RequestDirector { } roureq = followup; } - - userToken = this.userTokenHandler.getUserToken(context); - context.setAttribute(ClientContext.USER_TOKEN, userToken); - if (managedConn != null) { - managedConn.setState(userToken); + + if (managedConn != null && userToken == null) { + userToken = userTokenHandler.getUserToken(context); + context.setAttribute(ClientContext.USER_TOKEN, userToken); + if (userToken != null) { + managedConn.setState(userToken); + } } + } // while not done diff --git a/httpclient/src/main/java/org/apache/http/impl/client/DefaultUserTokenHandler.java b/httpclient/src/main/java/org/apache/http/impl/client/DefaultUserTokenHandler.java index 4d52a927e..9e8b05fdb 100644 --- a/httpclient/src/main/java/org/apache/http/impl/client/DefaultUserTokenHandler.java +++ b/httpclient/src/main/java/org/apache/http/impl/client/DefaultUserTokenHandler.java @@ -46,6 +46,16 @@ import org.apache.http.protocol.ExecutionContext; import org.apache.http.protocol.HttpContext; /** + * Default implementation of {@link UserTokenHandler}. This class will use + * an instance of {@link Principal} as a state object for HTTP connections, + * if it can be obtained from the given execution context. This helps ensure + * persistent connections created with a particular user identity within + * a particular security context can be reused by the same user only. + *

+ * DefaultUserTokenHandler will use the user principle of connection + * based authentication schemes such as NTLM or that of the SSL session + * with the client authentication turned on. If both are unavailable, + * null token will be returned. * * @since 4.0 */ diff --git a/httpclient/src/main/java/org/apache/http/impl/client/RoutedRequest.java b/httpclient/src/main/java/org/apache/http/impl/client/RoutedRequest.java index 3fc88d265..81d76d9f0 100644 --- a/httpclient/src/main/java/org/apache/http/impl/client/RoutedRequest.java +++ b/httpclient/src/main/java/org/apache/http/impl/client/RoutedRequest.java @@ -35,22 +35,16 @@ import net.jcip.annotations.NotThreadSafe; import org.apache.http.conn.routing.HttpRoute; - /** * A request with the route along which it should be sent. * - * - * - * - * @version $Revision$ - * * @since 4.0 */ @NotThreadSafe // RequestWrapper is @NotThreadSafe public class RoutedRequest { - private final RequestWrapper request; // @NotThreadSafe - private final HttpRoute route; // @Immutable + protected final RequestWrapper request; // @NotThreadSafe + protected final HttpRoute route; // @Immutable /** * Creates a new routed request. 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 cf484d405..364293575 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 @@ -91,11 +91,7 @@ public class BestMatchSpec implements CookieSpec { private NetscapeDraftSpec getNetscape() { if (this.netscape == null) { - String[] patterns = this.datepatterns; - if (patterns == null) { - patterns = BrowserCompatSpec.getDATE_PATTERNS(); - } - this.netscape = new NetscapeDraftSpec(patterns); + this.netscape = new NetscapeDraftSpec(this.datepatterns); } return netscape; } diff --git a/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpec.java b/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpec.java index 6ff92259e..32ac9d013 100644 --- a/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpec.java +++ b/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpec.java @@ -57,8 +57,8 @@ import org.apache.http.util.CharArrayBuffer; */ public class BrowserCompatSpec extends CookieSpecBase { - /** Valid date patterns used per default */ - private static final String[] DATE_PATTERNS = new String[] { + @Deprecated + protected static final String[] DATE_PATTERNS = new String[] { DateUtils.PATTERN_RFC1123, DateUtils.PATTERN_RFC1036, DateUtils.PATTERN_ASCTIME, @@ -75,6 +75,23 @@ public class BrowserCompatSpec extends CookieSpecBase { "EEE, dd-MM-yyyy HH:mm:ss z", }; + private static final String[] DEFAULT_DATE_PATTERNS = new String[] { + DateUtils.PATTERN_RFC1123, + DateUtils.PATTERN_RFC1036, + DateUtils.PATTERN_ASCTIME, + "EEE, dd-MMM-yyyy HH:mm:ss z", + "EEE, dd-MMM-yyyy HH-mm-ss z", + "EEE, dd MMM yy HH:mm:ss z", + "EEE dd-MMM-yyyy HH:mm:ss z", + "EEE dd MMM yyyy HH:mm:ss z", + "EEE dd-MMM-yyyy HH-mm-ss z", + "EEE dd-MMM-yy HH:mm:ss z", + "EEE dd MMM yy HH:mm:ss z", + "EEE,dd-MMM-yy HH:mm:ss z", + "EEE,dd-MMM-yyyy HH:mm:ss z", + "EEE, dd-MM-yyyy HH:mm:ss z", + }; + private final String[] datepatterns; /** Default constructor */ @@ -83,7 +100,7 @@ public class BrowserCompatSpec extends CookieSpecBase { if (datepatterns != null) { this.datepatterns = datepatterns.clone(); } else { - this.datepatterns = DATE_PATTERNS; + this.datepatterns = DEFAULT_DATE_PATTERNS; } registerAttribHandler(ClientCookie.PATH_ATTR, new BasicPathHandler()); registerAttribHandler(ClientCookie.DOMAIN_ATTR, new BasicDomainHandler()); @@ -189,10 +206,6 @@ public class BrowserCompatSpec extends CookieSpecBase { return null; } - protected static String[] getDATE_PATTERNS() { - return DATE_PATTERNS.clone(); - } - @Override public String toString() { return "compatibility";