You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2009/06/04 20:17:39 UTC
svn commit: r781821 - in
/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http:
client/ client/params/ client/protocol/ impl/client/ impl/cookie/
Author: olegk
Date: Thu Jun 4 18:17:38 2009
New Revision: 781821
URL: http://svn.apache.org/viewvc?rev=781821&view=rev
Log:
Javadoc cleanups; fixed some binary incompatibilities with 4.0-beta1
Modified:
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/HttpClient.java
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/UserTokenHandler.java
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/params/ClientPNames.java
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/protocol/ClientContext.java
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/AbstractHttpClient.java
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultHttpClient.java
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultRedirectHandler.java
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultRequestDirector.java
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultUserTokenHandler.java
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/RoutedRequest.java
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpec.java
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpec.java
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/HttpClient.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/HttpClient.java?rev=781821&r1=781820&r2=781821&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/HttpClient.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/HttpClient.java Thu Jun 4 18:17:38 2009
@@ -96,6 +96,11 @@
* 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();
* }
* </PRE>
*
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/UserTokenHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/UserTokenHandler.java?rev=781821&r1=781820&r2=781821&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/UserTokenHandler.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/UserTokenHandler.java Thu Jun 4 18:17:38 2009
@@ -40,9 +40,8 @@
* <code>null</code> if the context does not contain any resources or details
* specific to the current user.
* <p/>
- * 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
*/
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/params/ClientPNames.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/params/ClientPNames.java?rev=781821&r1=781820&r2=781821&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/params/ClientPNames.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/params/ClientPNames.java Thu Jun 4 18:17:38 2009
@@ -60,7 +60,8 @@
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.
* <p>
* This parameter expects a value of type {@link Boolean}.
* </p>
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/protocol/ClientContext.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/protocol/ClientContext.java?rev=781821&r1=781820&r2=781821&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/protocol/ClientContext.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/protocol/ClientContext.java Thu Jun 4 18:17:38 2009
@@ -97,6 +97,10 @@
*/
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";
}
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/AbstractHttpClient.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/AbstractHttpClient.java?rev=781821&r1=781820&r2=781821&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/AbstractHttpClient.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/AbstractHttpClient.java Thu Jun 4 18:17:38 2009
@@ -71,10 +71,14 @@
import org.apache.http.protocol.HttpRequestExecutor;
/**
- * Base class for {@link HttpClient} implementations.
- * <p>
- * 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:
* <ul>
* <li>{@link HttpRequestExecutor}</li> object used to transmit messages
* over HTTP connections. The {@link #createRequestExecutor()} must be
@@ -130,8 +134,25 @@
* response received from the target server.
* The {@link #createRedirectHandler()} must be implemented
* by concrete super classes to instantiate this object.
- * <li>{@link UserTokenHandler}</li>
+ * <li>{@link UserTokenHandler}</li> object used to determine if the
+ * execution context is user identity specific.
+ * The {@link #createUserTokenHandler()()} must be implemented by
+ * concrete super classes to instantiate this object.
* </ul>
+ * <p>
+ * 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.
+ * <p>
+ * 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
*/
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultHttpClient.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultHttpClient.java?rev=781821&r1=781820&r2=781821&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultHttpClient.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultHttpClient.java Thu Jun 4 18:17:38 2009
@@ -86,16 +86,73 @@
import org.apache.http.protocol.RequestUserAgent;
import org.apache.http.util.VersionInfo;
-
-
/**
- * Default implementation of an HTTP client.
- * <br/>
- * This class replaces <code>HttpClient</code> in HttpClient 3.
- *
- *
- * <!-- empty lines to avoid svn diff problems -->
- * @version $Revision$
+ * Default implementation of {@link AbstractHttpClient}.
+ * <p>
+ * This class creates an instance of {@link SingleClientConnManager}
+ * for connection management if not explicitly set.
+ * <p>
+ * This class creates the following chain of protocol interceptors per
+ * default:
+ * <ul>
+ * <li>{@link RequestDefaultHeaders}</li>
+ * <li>{@link RequestContent}</li>
+ * <li>{@link RequestTargetHost}</li>
+ * <li>{@link RequestConnControl}</li>
+ * <li>{@link RequestUserAgent}</li>
+ * <li>{@link RequestExpectContinue}</li>
+ * <li>{@link RequestAddCookies}</li>
+ * <li>{@link ResponseProcessCookies}</li>
+ * <li>{@link RequestTargetAuthentication}</li>
+ * <li>{@link RequestProxyAuthentication}</li>
+ * </ul>
+ * <p>
+ * This class sets up the following parameters if not explicitly set:
+ * <ul>
+ * <li>Version: HttpVersion.HTTP_1_1</li>
+ * <li>ContentCharset: HTTP.DEFAULT_CONTENT_CHARSET</li>
+ * <li>UseExpectContinue: true</li>
+ * <li>NoTcpDelay: true</li>
+ * <li>SocketBufferSize: 8192</li>
+ * <li>UserAgent: Apache-HttpClient/release (java 1.5)</li>
+ * </ul>
+ * <p>
+ * The following parameters can be used to customize the behavior of this
+ * class:
+ * <ul>
+ * <li>{@link org.apache.http.params.CoreProtocolPNames#PROTOCOL_VERSION}</li>
+ * <li>{@link org.apache.http.params.CoreProtocolPNames#STRICT_TRANSFER_ENCODING}</li>
+ * <li>{@link org.apache.http.params.CoreProtocolPNames#HTTP_ELEMENT_CHARSET}</li>
+ * <li>{@link org.apache.http.params.CoreProtocolPNames#USE_EXPECT_CONTINUE}</li>
+ * <li>{@link org.apache.http.params.CoreProtocolPNames#WAIT_FOR_CONTINUE}</li>
+ * <li>{@link org.apache.http.params.CoreProtocolPNames#USER_AGENT}</li>
+ * <li>{@link org.apache.http.params.CoreConnectionPNames#SOCKET_BUFFER_SIZE}</li>
+ * <li>{@link org.apache.http.params.CoreConnectionPNames#MAX_LINE_LENGTH}</li>
+ * <li>{@link org.apache.http.params.CoreConnectionPNames#MAX_HEADER_COUNT}</li>
+ * <li>{@link org.apache.http.params.CoreConnectionPNames#SO_TIMEOUT}</li>
+ * <li>{@link org.apache.http.params.CoreConnectionPNames#SO_LINGER}</li>
+ * <li>{@link org.apache.http.params.CoreConnectionPNames#TCP_NODELAY}</li>
+ * <li>{@link org.apache.http.params.CoreConnectionPNames#CONNECTION_TIMEOUT}</li>
+ * <li>{@link org.apache.http.params.CoreConnectionPNames#STALE_CONNECTION_CHECK}</li>
+ * <li>{@link org.apache.http.conn.params.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#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#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#HANDLE_AUTHENTICATION}</li>
+ * <li>{@link org.apache.http.client.params.ClientPNames#HANDLE_REDIRECTS}</li>
+ * <li>{@link org.apache.http.client.params.ClientPNames#MAX_REDIRECTS}</li>
+ * <li>{@link org.apache.http.client.params.ClientPNames#ALLOW_CIRCULAR_REDIRECTS}</li>
+ * <li>{@link org.apache.http.client.params.ClientPNames#VIRTUAL_HOST}</li>
+ * <li>{@link org.apache.http.client.params.ClientPNames#DEFAULT_HOST}</li>
+ * <li>{@link org.apache.http.client.params.ClientPNames#DEFAULT_HEADERS}</li>
+ * <li>{@link org.apache.http.client.params.ClientPNames#CONNECTION_MANAGER_FACTORY_CLASS_NAME}</li>
+ * </ul>
*
* @since 4.0
*/
@@ -126,17 +183,6 @@
}
- /**
- * Creates a new BasicHttpParams object, and sets up the following:
- * <ul>
- * <li>Version: HttpVersion.HTTP_1_1</li>
- * <li>ContentCharset: HTTP.DEFAULT_CONTENT_CHARSET</li>
- * <li>UseExpectContinue: true</li>
- * <li>NoTcpDelay: true</li>
- * <li>SocketBufferSize: 8192</li>
- * <li>UserAgent: Apache-HttpClient/release (java 1.5)</li>
- * </ul>
- */
@Override
protected HttpParams createHttpParams() {
HttpParams params = new BasicHttpParams();
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultRedirectHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultRedirectHandler.java?rev=781821&r1=781820&r2=781821&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultRedirectHandler.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultRedirectHandler.java Thu Jun 4 18:17:38 2009
@@ -52,14 +52,8 @@
import org.apache.http.protocol.HttpContext;
import org.apache.http.protocol.ExecutionContext;
-
/**
* Default implementation of {@link RedirectHandler}.
- *
- *
- *
- * <!-- empty lines to avoid svn diff problems -->
- * @version $Revision$
*
* @since 4.0
*/
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultRequestDirector.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultRequestDirector.java?rev=781821&r1=781820&r2=781821&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultRequestDirector.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultRequestDirector.java Thu Jun 4 18:17:38 2009
@@ -533,12 +533,15 @@
}
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
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultUserTokenHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultUserTokenHandler.java?rev=781821&r1=781820&r2=781821&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultUserTokenHandler.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/DefaultUserTokenHandler.java Thu Jun 4 18:17:38 2009
@@ -46,6 +46,16 @@
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.
+ * <p>
+ * 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,
+ * <code>null</code> token will be returned.
*
* @since 4.0
*/
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/RoutedRequest.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/RoutedRequest.java?rev=781821&r1=781820&r2=781821&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/RoutedRequest.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/RoutedRequest.java Thu Jun 4 18:17:38 2009
@@ -35,22 +35,16 @@
import org.apache.http.conn.routing.HttpRoute;
-
/**
* A request with the route along which it should be sent.
*
- *
- *
- * <!-- empty lines to avoid svn diff problems -->
- * @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.
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpec.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpec.java?rev=781821&r1=781820&r2=781821&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpec.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/cookie/BestMatchSpec.java Thu Jun 4 18:17:38 2009
@@ -91,11 +91,7 @@
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;
}
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpec.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpec.java?rev=781821&r1=781820&r2=781821&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpec.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/cookie/BrowserCompatSpec.java Thu Jun 4 18:17:38 2009
@@ -57,8 +57,8 @@
*/
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 @@
"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 @@
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 @@
return null;
}
- protected static String[] getDATE_PATTERNS() {
- return DATE_PATTERNS.clone();
- }
-
@Override
public String toString() {
return "compatibility";