[Httpcomponents Wiki] Update of "HttpClientTutorial" by OlegKalnichevski

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Httpcomponents Wiki" for change notification.

The following page has been changed by OlegKalnichevski:
http://wiki.apache.org/HttpComponents/HttpClientTutorial

------------------------------------------------------------------------------
    
    Quite naturally, the main entry point of the HttpClient API is the HttpClient interface that defines the contract described above.
  
-   Here is an example of method execution process in its simplest form:
+   Here is an example of request execution process in its simplest form:
  
  {{{
  HttpClient httpclient = new DefaultHttpClient();
@@ -135, +135 @@

  2
  }}}
  
- There is an efficient way to obtain all headers of a given type using the HeaderIterator interface.
+ The most efficient way to obtain all headers of a given type is by using the HeaderIterator interface.
  
  {{{
  HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1_1, 
@@ -507, +507 @@

  
  === Aborting requests ===
  
-     In some situations HTTP request execution fail to complete within the expected time frame due to high load on the target server or too many concurrent requests executed on the client side. In such cases it may be necessary to terminate the request prematurely and unblock the execution thread blocked in a I/O operation. HTTP requests being executed by HttpClient can be aborted at any stage of execution by invoking HttpUriRequest#abort method. This method is thread-safe and can be called from any thread. When an HTTP request is aborted its execution thread blocked in an I/O operation is guaranteed to unblock by throwing a InterruptedIOException
+     In some situations HTTP request execution fail to complete within the expected time frame due to high load on the target server or too many concurrent requests issued on the client side. In such cases it may be necessary to terminate the request prematurely and unblock the execution thread blocked in a I/O operation. HTTP requests being executed by HttpClient can be aborted at any stage of execution by invoking HttpUriRequest#abort method. This method is thread-safe and can be called from any thread. When an HTTP request is aborted its execution thread blocked in an I/O operation is guaranteed to unblock by throwing a InterruptedIOException
  
  == HTTP protocol interceptors ==
  
@@ -554, +554 @@

  
  == HTTP parameters ==
  
-     HttpParams interface represents a collection of immutable values that define a runtime behavior of a component. In many ways HttpParams  is similar to HttpContext. The main distinction between the two lies in their use at runtime. Both interfaces represent a collection of objects that are organized as a map of textual names to object values, but serve distinct purposes:
+     HttpParams interface represents a collection of immutable values that define a runtime behavior of a component. In many ways HttpParams  is similar to HttpContext. The main distinction between the two lies in their use at runtime. Both interfaces represent a collection of objects that are organized as a map of keys to object values, but serve distinct purposes:
  
      * HttpParams is intended to contain simple objects: integers, doubles, strings, collections and objects that remain immutable at runtime. HttpParams is expected to be used in the 'write once - ready many' mode. HttpContext is intended to contain complex objects that are very likely to mutate in the course of HTTP message processing.
      
@@ -605, +605 @@

  
  === HTTP parameters beans ===
  
-     HttpParams interface allows for a great deal of flexibility in handling configuration of components. Most importantly, new parameters can be introduced without affecting binary compatibility with older versions. However, HttpParams also has a certain disadvantage compared to regular Java beans: HttpParams cannot be assembled using a DI framework. To mitigate the limitation, HttpCore includes a number of bean classes that can used in order to initialize HttpParams objects using standard Java bean conventions. 
+     HttpParams interface allows for a great deal of flexibility in handling configuration of components. Most importantly, new parameters can be introduced without affecting binary compatibility with older versions. However, HttpParams also has a certain disadvantage compared to regular Java beans: HttpParams cannot be assembled using a DI framework. To mitigate the limitation, HttpClient includes a number of bean classes that can used in order to initialize HttpParams objects using standard Java bean conventions. 
  
  {{{
  HttpParams params = new BasicHttpParams();
@@ -646, +646 @@

  
      * '''http.protocol.strict-transfer-encoding''': defines whether responses with an invalid {{{Transfer-Encoding}}} header should be rejected. This parameter expects a value of type java.lang.Boolean. If this parameter is not set invalid {{{Transfer-Encoding}}} values will be ignored.
  
-     * '''http.protocol.expect-continue''': activates 'Expect: 100-Continue' handshake for the entity enclosing methods. The purpose of the {{{Expect: 100-Continue}}} handshake is to allow a client that is sending a request message with a request body to determine if the origin server is willing to accept the request (based on the request headers) before the client sends the request body. The use of the {{{Expect: 100-continue}}} handshake can result in a noticeable performance improvement for entity enclosing requests (such as POST and PUT) that require the target server's authentication. {{{Expect: 100-continue}}} handshake should be used with caution, as it may cause problems with HTTP servers and proxies that do not support HTTP/1.1 protocol. This parameter expects a value of type java.lang.Boolean. If this parameter is not set HttpClient will attempt to use the handshake. 
+     * '''http.protocol.expect-continue''': activates 'Expect: 100-Continue' handshake for the entity enclosing methods. The purpose of the {{{Expect: 100-Continue}}} handshake is to allow the client that is sending a request message with a request body to determine if the origin server is willing to accept the request (based on the request headers) before the client sends the request body. The use of the {{{Expect: 100-continue}}} handshake can result in a noticeable performance improvement for entity enclosing requests (such as POST and PUT) that require the target server's authentication. {{{Expect: 100-continue}}} handshake should be used with caution, as it may cause problems with HTTP servers and proxies that do not support HTTP/1.1 protocol. This parameter expects a value of type java.lang.Boolean. If this parameter is not set HttpClient will attempt to use the handshake. 
  
      * '''http.protocol.wait-for-continue''': defines the maximum period of time in milliseconds the client should spend waiting for a 100-continue response. This parameter expects a value of type java.lang.Integer. If this parameter is not set HttpClient will wait 3 seconds for a confirmation before resuming the transmission of the request body.
  
@@ -684, +684 @@

    
  == HTTP connection routing ==
  
-     HttpClient can establish connections to the target host either directly or via a complex route that involves multiple intermediate connections also referred to as hops. HttpClient differentiates connections of a route into plain, tunneled and layered. The use of multiple intermediate proxies to tunnel connections to the target host is referred to as proxy chaining.
+     HttpClient is capable of establishing connections to the target host either directly or via a route that may involve multiple intermediate connections also referred to as hops. HttpClient differentiates connections of a route into plain, tunneled and layered. The use of multiple intermediate proxies to tunnel connections to the target host is referred to as proxy chaining.
      
-     Plain routes are established by connecting to the target or the first proxy. Tunnelled routes are established by connecting to the first and tunnelling through a chain of proxies to the target. Routes without a proxy cannot be tunnelled. Layered routes are established by layering a protocol over an existing connection. Protocols can only be layered over a tunnel to the target, or over a direct connection without proxies.
+     Plain routes are established by connecting to the target or the first and only proxy. Tunnelled routes are established by connecting to the first and tunnelling through a chain of proxies to the target. Routes without a proxy cannot be tunnelled. Layered routes are established by layering a protocol over an existing connection. Protocols can only be layered over a tunnel to the target, or over a direct connection without proxies.
  
  === Route computation ===
  
-     RouteInfo interface represents information about a definitive route to a target host involving one or more intermediate steps or hops. HttpRoute is a concrete implementation of RouteInfo, which cannot be changed (is immutable). HttpTracker is a mutable RouteInfo implementation used internally by HttpClient to track the remaining hops to the ultimate route target. HttpTracker can be updated after a successful execution of the next hop towards to route target. HttpRouteDirector is a helper class that can be used to compute the next step in a route. This class is used internally by HttpClient.
+     RouteInfo interface represents information about a definitive route to a target host involving one or more intermediate steps or hops. HttpRoute is a concrete implementation of RouteInfo, which cannot be changed (is immutable). HttpTracker is a mutable RouteInfo implementation used internally by HttpClient to track the remaining hops to the ultimate route target. HttpTracker can be updated after a successful execution of the next hop towards the route target. HttpRouteDirector is a helper class that can be used to compute the next step in a route. This class is used internally by HttpClient.
  
      HttpRoutePlanner is an interface representing a strategy to compute a complete route to a given target based on the execution context. HttpClient ships with two default HttpRoutePlanner implementation. ProxySelectorRoutePlanner is based on java.net.ProxySelector. By default, it will pick up the proxy settings of the JVM, either from system properties or from the browser running the application. DefaultHttpRoutePlanner implementation does not make use of any Java system properties, nor of system or browser proxy settings. It computes routes based exclusively on HTTP parameters described below.
  
@@ -706, +706 @@

  
  === Secure HTTP connections ===
  
-     HTTP connections can be considered secure if information transmitted between two connection endpoints cannot be read or tampered with by unauthorized third party. The SSL/TLS protocol is the most widely used technique to ensure HTTP transport security. However, other encryption techniques could be employed as well. Usually, HTTP transport is layered over the SSL/TLS encrypted connection.
+     HTTP connections can be considered secure if information transmitted between two connection endpoints cannot be read or tampered with by an unauthorized third party. The SSL/TLS protocol is the most widely used technique to ensure HTTP transport security. However, other encryption techniques could be employed as well. Usually, HTTP transport is layered over the SSL/TLS encrypted connection.
  
  == Socket factories ==
  
@@ -853, +853 @@

  
      HTTP connections are complex, stateful, thread-unsafe objects which need to be properly managed to function correctly. HTTP connections can only be used by one execution thread at a time. HttpClient employs a special entity to manage access to HTTP connections called HTTP connection manager and represented by the ClientConnectionManager interface. The purpose of an HTTP connection manager is to serve as a factory for new HTTP connections, manage persistent connections and synchronize access to persistent connections making sure that only one thread can have access to a connection at a time.
  
-     Internally HTTP connection managers work with instances of OperatedClientConnection, but they hands out instances of ManagedClientConnection to the service consumers. ManagedClientConnection acts as a wrapper for a OperatedClientConnection instance that manages its state and controls all I/O operations on that connection. It also abstracts away socket operations and provides convenient methods for opening and updating sockets in order to establish a route. ManagedClientConnection instances are aware of their link to the connection manager that spawned them and of the fact that they must be returned back to the manager when no longer in use. ManagedClientConnection classes also implement ConnectionReleaseTrigger interface that can be used to trigger the release of the connection back to the manager. Once the connection release has been triggered the wrapped connection gets detached from the ManagedClientConnection wrapper and the OperatedClientConnection instance is retu
 rned back to the manager. Even though the service consumer still holds a reference to the ManagedClientConnection instance, it is no longer able to execute any I/O operation or change the state of the OperatedClientConnection either intentionally or unintentionally.
+     Internally HTTP connection managers work with instances of OperatedClientConnection, but they hands out instances of ManagedClientConnection to the service consumers. ManagedClientConnection acts as a wrapper for a OperatedClientConnection instance that manages its state and controls all I/O operations on that connection. It also abstracts away socket operations and provides convenience methods for opening and updating sockets in order to establish a route. ManagedClientConnection instances are aware of their link to the connection manager that spawned them and of the fact that they must be returned back to the manager when no longer in use. ManagedClientConnection classes also implement ConnectionReleaseTrigger interface that can be used to trigger the release of the connection back to the manager. Once the connection release has been triggered the wrapped connection gets detached from the ManagedClientConnection wrapper and the OperatedClientConnection instance is ret
 urned back to the manager. Even though the service consumer still holds a reference to the ManagedClientConnection instance, it is no longer able to execute any I/O operation or change the state of the OperatedClientConnection either intentionally or unintentionally.
  
-     This is an example of acquiring a connection from the connection manager:  
+     This is an example of acquiring a connection from a connection manager:  
      
  {{{
  HttpParams params = new BasicHttpParams();
@@ -915, +915 @@

  
      These are parameters that be used to customize standard HTTP connection manager implementations:
  
-     * '''http.conn-manager.timeout''': Defines the timeout in milliseconds used when retrieving an instance of ManagedClientConnection from the ClientConnectionManager This parameter expects a value of type java.lang.Long.
+     * '''http.conn-manager.timeout''': Defines the timeout in milliseconds used when retrieving an instance of ManagedClientConnection from the ClientConnectionManager This parameter expects a value of type java.lang.Long. If this parameter is not set connection requests will not time out (infinite timeout).
  
      * '''http.conn-manager.max-per-route''': Defines the maximum number of connections per route. This limit is interpreted by client connection managers and applies to individual manager instances. This parameter expects a value of type ConnPerRoute.
  
@@ -974, +974 @@

  
  === Multithreaded request execution ===
  
-     When equipped with a pooling connection manager such as ThreadSafeClientConnManager HttpClient can be used to execute multiple requests simultaneously using multiple threads of execution. DefaultHttpClient plus ThreadSafeClientConnManager is fully thread safe.
+     When equipped with a pooling connection manager such as ThreadSafeClientConnManager HttpClient can be used to execute multiple requests simultaneously using multiple threads of execution.
  
-     ThreadSafeClientConnManager will allocate connections based on its configuration. If all connections for a given route has already been leased, a request for connection will block until a connection is released back to the pool. One can ensure the connection manager does not block indefinitely in the connection request operation by setting 'http.conn-manager.timeout' to a positive value. If the connection request cannot be serviced within the given time period ConnectionPoolTimeoutException will be thrown.
+     ThreadSafeClientConnManager will allocate connections based on its configuration. If all connections for a given route have already been leased, a request for connection will block until a connection is released back to the pool. One can ensure the connection manager does not block indefinitely in the connection request operation by setting 'http.conn-manager.timeout' to a positive value. If the connection request cannot be serviced within the given time period ConnectionPoolTimeoutException will be thrown.
  
  {{{
  HttpParams params = new BasicHttpParams();
@@ -1050, +1050 @@

  
      One of the major shortcoming of the classic blocking I/O model is that the network socket can react to I/O events only when blocked in an I/O operation. When a connection is released back to the manager, it can be kept alive however it is unable to monitor the status of the socket and react to any I/O events. If the connection gets closed on the server side, the client side connection is unable to detect the change in the connection state and react appropriately by closing the socket on its end. 
  
-     HttpClient tries to mitigate the problem by testing whether the connection is 'stale', that is no longer valid because it was closed on the server side. The stale connection check is not 100% reliable and adds 10 to 30 ms overhead to each request execution. The only feasible solution that does not involve a one thread per socket model for idle connections is a dedicated monitor thread used to evict connections that are considered expired due to a long period of inactivity. The monitor thread can periodically call ClientConnectionManager#closeExpiredConnections() method to close all expired connections and evict closed connections from the pool. It can also optionally call ClientConnectionManager#closeIdleConnections() method to close all connections that have been idle over a given period of time. 
+     HttpClient tries to mitigate the problem by testing whether the connection is 'stale', that is no longer valid because it was closed on the server side, prior to using the connection for executing an HTTP request. The stale connection check is not 100% reliable and adds 10 to 30 ms overhead to each request execution. The only feasible solution that does not involve a one thread per socket model for idle connections is a dedicated monitor thread used to evict connections that are considered expired due to a long period of inactivity. The monitor thread can periodically call ClientConnectionManager#closeExpiredConnections() method to close all expired connections and evict closed connections from the pool. It can also optionally call ClientConnectionManager#closeIdleConnections() method to close all connections that have been idle over a given period of time. 
      
  {{{
  public static class IdleConnectionMonitorThread extends Thread {
@@ -1132, +1132 @@

  
      Originally HTTP was designed as a stateless, request / response oriented protocol that made no special provisions for stateful sessions spanning across several logically related request / response exchanges. As HTTP protocol grew in popularity and adoption more and more systems began to use it for applications it was never intended for, for instance as a transport for e-commerce applications. Thus, the support for state management became a necessity. 
      
-     Netscape Communications, at that time a leading developer of web client and server software, implemented support for HTTP state management in their products based on a proprietary specification. Later, Netscape tried to standardise the mechanism by publishing a specification draft. Those efforts contributed to the formal specification defined through the  RFC standard track. However, state management in a significant number of applications is still largely based on the Netscape draft and is incompatible with the official specification. All major developers of web browsers felt compelled to retain compatibility with those applications greatly contributing to the fragmentation of standards compliance and compatibility issues.
+     Netscape Communications, at that time a leading developer of web client and server software, implemented support for HTTP state management in their products based on a proprietary specification. Later, Netscape tried to standardise the mechanism by publishing a specification draft. Those efforts contributed to the formal specification defined through the  RFC standard track. However, state management in a significant number of applications is still largely based on the Netscape draft and is incompatible with the official specification. All major developers of web browsers felt compelled to retain compatibility with those applications greatly contributing to the fragmentation of standards compliance.
  
  == HTTP cookies ==
  
@@ -1213, +1213 @@

  
      These are parameters that be used to customize HTTP state management and behaviour of individual cookie specifications:
      
-     * '''http.protocol.cookie-datepatterns''': 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 java.util.Collection. The collection elements must be of type java.lang.String compatible with the syntax of java.text.SimpleDateFormat.
+     * '''http.protocol.cookie-datepatterns''': 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 java.util.Collection. The collection elements must be of type java.lang.String compatible with the syntax of java.text.SimpleDateFormat. If this parameter is not set the choice of a default value is CookieSpec implementation specific. Please note this parameter applies 
      
-     * '''http.protocol.single-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 java.lang.Boolean. Please note this parameter applies to strict cookie specifications (RFC 2109 and RFC 2965) only. Browser compatibility and netscape draft policies will always put all cookies into one request header.
+     * '''http.protocol.single-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 java.lang.Boolean. If this parameter is not set the choice of a default value is CookieSpec implementation specific. Please note this parameter applies to strict cookie specifications (RFC 2109 and RFC 2965) only. Browser compatibility and netscape draft policies will always put all cookies into one request header. 
  
-     * '''http.protocol.cookie-policy''': defines the name of a cookie specification to be used for HTTP state management. This parameter expects a value of type java.lang.String.
+     * '''http.protocol.cookie-policy''': defines the name of a cookie specification to be used for HTTP state management. This parameter expects a value of type java.lang.String. If this parameter is not set valid date patterns are CookieSpec implementation specific.
  
  == Cookie specification registry ==
  
@@ -1274, +1274 @@

  
  == Cookie persistence ==
  
-     HttpClient can work with any physical representation of a persistent cookie store that implements the CookieStore interface. The default CookieStore implementation called BasicClientCookie is a simple, in-memory implementation backed by a java.util.List. Cookies stored in an BasicClientCookie object are lost when the container object get garbage collected. Users can provide more complex implementations if necessary. 
+     HttpClient can work with any physical representation of a persistent cookie store that implements the CookieStore interface. The default CookieStore implementation called BasicClientCookie is a simple implementation backed by a java.util.List. Cookies stored in an BasicClientCookie object are lost when the container object get garbage collected. Users can provide more complex implementations if necessary. 
  
  {{{
  DefaultHttpClient httpclient = new DefaultHttpClient();
@@ -1320, +1320 @@

      
  === Per user / thread state management ===
      
-     One can use an individual local execution context in order to implement per user / thread state management. Cookie specification registry and cookie store defined in the local context will take precedence over the default ones set at the HTTP client level.
+     One can use an individual local execution context in order to implement per user (or per thread) state management. Cookie specification registry and cookie store defined in the local context will take precedence over the default ones set at the HTTP client level.
  
  {{{
  HttpClient httpclient = new DefaultHttpClient();
@@ -1341, +1341 @@

  
  == User credentials ==
    
-   Any process sof user authentication requires a set of credentials that can be used to establish user identity. In the simplest form user crednetials can be just a user name / password pair. UsernamePasswordCredentials represents a set of credentials consisting of a security principal and a password in clear text. This implementation is sufficient for standard authentication schemes defined by the HTTP standard specification. 
+   Any process of user authentication requires a set of credentials that can be used to establish user identity. In the simplest form user crednetials can be just a user name / password pair. UsernamePasswordCredentials represents a set of credentials consisting of a security principal and a password in clear text. This implementation is sufficient for standard authentication schemes defined by the HTTP standard specification. 
    
  {{{
  UsernamePasswordCredentials creds = new UsernamePasswordCredentials("user", "pwd");
@@ -1355, +1355 @@

  pwd
  }}}
  
-     NTCredentials is a Microsoft Windows specific implementation that includes in addition to the user name / password pair a set of additional Windows specific attributes such as the name of the user domain, as in Microsoft Windows network the same user can belong to multiple domains with a different set of authorizations.
+     NTCredentials is a Microsoft Windows specific implementation that includes in addition to the user name / password pair a set of additional Windows specific attributes such as a name of the user domain, as in Microsoft Windows network the same user can belong to multiple domains with a different set of authorizations.
  
  {{{
  NTCredentials creds = new NTCredentials("user", "pwd", "workstation", "domain");
@@ -1385, +1385 @@

      
      * '''Basic''': Basic authentication scheme as defined in RFC 2617. This authentication scheme is insecure, as the credentials are transmitted in clear text. Despite its insecurity Basic authentication scheme is perfectly adequate if used in combination with the TLS/SSL encryption.
    
-     * '''Digest''': Digest authentication scheme as defined in RFC 2617. Digest authentication scheme is considered more secure than Basic and can be a good choice for those applications that do not want the overhead of full transport security through TLS/SSL encryption.
+     * '''Digest''': Digest authentication scheme as defined in RFC 2617. Digest authentication scheme is significantly more secure than Basic and can be a good choice for those applications that do not want the overhead of full transport security through TLS/SSL encryption.
    
      * '''NTLM authentication''': NTLM is a proprietary authentication scheme developed by Microsoft and optimized for Windows platforms. NTLM is believed to be more secure than Digest. This scheme is supported only partially and requires an external NTLM engine. For details please refer to the NTLM_SUPPORT.txt document included with HttpClient distributions.
  
@@ -1393, +1393 @@

      
      These are parameters that be used to customize HTTP authentication process and behaviour of individual authentication schemes:
      
-     * '''http.protocol.handle-authentication''': defines whether authentication should be handled automatically. This parameter expects a value of type java.lang.Boolean.
+     * '''http.protocol.handle-authentication''': defines whether authentication should be handled automatically. This parameter expects a value of type java.lang.Boolean. If this parameter is not set HttpClient will handle authentication automatically.
  
-     * '''http.auth.credential-charset''': defines the charset to be used when encoding user credentials. This parameter expects a value of type java.lang.String.
+     * '''http.auth.credential-charset''': defines the charset to be used when encoding user credentials. This parameter expects a value of type java.lang.String. If this parameter is not set US-ASCII will be used.
      
  == Authentication scheme registry ==
  
@@ -1411, +1411 @@

      
      Credentials providers are intended to maintain a set of user credentials and to be able to produce user credentials for a particular authentication scope. Authentication scope consists of a host name, a port number, a realm name and an authentication scheme name. When registering credentials with the credentials provider one can provide a wild card (any host, any port, any realm, any scheme) instead of a concrete attribute value. The credentials provider is then expected to be able to find the closest match for a particular scope if the direct match cannot be found. 
      
-     HttpClient can work with any physical representation of a credentials provider that implements the CredentialsProvider interface. The default CredentialsProvider implementation called BasicCredentialsProvider is a simple, in-memory implementation backed by a java.util.HashMap.
+     HttpClient can work with any physical representation of a credentials provider that implements the CredentialsProvider interface. The default CredentialsProvider implementation called BasicCredentialsProvider is a simple implementation backed by a java.util.HashMap.
  
  {{{
  CredentialsProvider credsProvider = new BasicCredentialsProvider();
@@ -1521, +1521 @@

      
  = HTTP client =
  
-     HttpClient interface represents only the most basic contract for HTTP request execution. It imposes no restrictions or particular details on the request execution process and leaves the specifics of connection management, state management, authentication and redirect handling up to individual implementations. This should make it easier to decorate the interface with additional functionality such as response content caching.
+     HttpClient interface represents the most essential contract for HTTP request execution. It imposes no restrictions or particular details on the request execution process and leaves the specifics of connection management, state management, authentication and redirect handling up to individual implementations. This should make it easier to decorate the interface with additional functionality such as response content caching.
  
+     DefaultHttpClient is the default implementation of the HttpClient interface. This class acts as a facade to a number of special purpose handler or strategy interface 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.
+     
+ {{{
+ DefaultHttpClient httpclient = new DefaultHttpClient();
+ 
+ httpclient.setKeepAliveStrategy(new DefaultConnectionKeepAliveStrategy() {
+ 
+ 	@Override
+ 	public long getKeepAliveDuration(
+ 			HttpResponse response,
+ 			HttpContext context) {
+ 		long keepAlive = super.getKeepAliveDuration(response, context);
+ 		if (keepAlive == -1) {
+ 			// Keep connections alive 5 seconds if a keep-alive value 
+ 			// has not be explicitly set by the server 
+ 			keepAlive = 5000;
+ 		}
+ 		return keepAlive;
+ 	}
+ 	
+ });
+ }}}    
+     
+     DefaultHttpClient 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 java.util.ArrayList. They are executed in the same natural order as they are added to the list.
+     
+ {{{
+ DefaultHttpClient httpclient = new DefaultHttpClient();
+ httpclient.removeRequestInterceptorByClass(RequestUserAgent.class);
+ httpclient.addRequestInterceptor(new HttpRequestInterceptor() {
+ 
+ 	public void process(
+ 			HttpRequest request, HttpContext context)
+ 			throws HttpException, IOException {
+ 		request.setHeader(HTTP.USER_AGENT, "My-own-client");
+ 	}
+ 	
+ });
+ }}}    
+     
+     DefaultHttpClient 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 the ClientConnectionManager#shutdown() method.
+     
+ {{{
+ HttpClient httpclient = new DefaultHttpClient();
+ // Do something useful
+ httpclient.getConnectionManager().shutdown();
+ }}}
+     
  == HTTP client parameters ==
  
      These are parameters that be used to customize the behaviour of the default HttpClient implementation:
  
-     * '''http.protocol.handle-redirects''': defines whether redirects should be handled automatically. This parameter expects a value of type java.lang.Boolean.
+     * '''http.protocol.handle-redirects''': defines whether redirects should be handled automatically. This parameter expects a value of type java.lang.Boolean. If this parameter is not HttpClient will handle redirects automatically.
  
-     * '''http.protocol.reject-relative-redirect''': defines whether relative redirects should be rejected. This parameter expects a value of type java.lang.Boolean.
+     * '''http.protocol.reject-relative-redirect''': defines whether relative redirects should be rejected. HTTP specification requires the location value be an absolute URI. This parameter expects a value of type java.lang.Boolean. If this parameter is not set relative redirects will be allowed. 
  
-     * '''http.protocol.max-redirects''': defines the maximum number of redirects to be followed. The limit on number of redirects is intended to prevent infinite loops caused by broken server side scripts. This parameter expects a value of type java.lang.Integer.
+     * '''http.protocol.max-redirects''': defines the maximum number of redirects to be followed. The limit on number of redirects is intended to prevent infinite loops caused by broken server side scripts. This parameter expects a value of type java.lang.Integer. If this parameter is not set no more than 100 redirects will be allowed.
  
-     * '''http.protocol.allow-circular-redirects''': defines whether circular redirects (redirects to the same location) should be allowed. The HTTP spec is not sufficiently clear whether circular redirects are permitted, therefore optionally they can be enabled. This parameter expects a value of type java.lang.Boolean.
+     * '''http.protocol.allow-circular-redirects''': defines whether circular redirects (redirects to the same location) should be allowed. The HTTP spec is not sufficiently clear whether circular redirects are permitted, therefore optionally they can be enabled. This parameter expects a value of type java.lang.Boolean. If this parameter is not set circular redirects will be disallowed.
  
-     * '''http.connection-manager.factory-class-name''': defines the class name of the default ClientConnectionManager implementation. This parameter expects a value of type java.lang.String.
+     * '''http.connection-manager.factory-class-name''': defines the class name of the default ClientConnectionManager implementation. This parameter expects a value of type java.lang.String. If this parameter is not set SingleClientConnManager will be used per default.
      
-     * '''http.virtual-host''': defines the virtual host name to be used in the {{{Host}}} header instead of the physical host name. This parameter expects a value of type HttpHost.
+     * '''http.virtual-host''': defines the virtual host name to be used in the {{{Host}}} header instead of the physical host name. This parameter expects a value of type HttpHost. If this parameter is not set name or IP address of the target host will be used.
      
      * '''http.default-headers''': defines the request headers to be sent per default with each request. This parameter expects a value of type ava.util.Collection containing Header objects. 
  
@@ -1547, +1594 @@

  
    HttpClient handles all types of redirects automatically, except those explicitly prohibited by the HTTP specification as requiring user intervention. Redirects on POST and PUT requests are converted to GET requests as required by the HTTP specification.
    
- == Default HTTP client and execution context ==
+ == HTTP client and execution context ==
  
      The DefaultHttpClient treats HTTP requests as immutable objects that are never supposed to change in the course of request execution. Instead, it creates a private mutable copy of the original request object, whose properties can be updated depending on the execution context. Therefore the final request properties such as the target host and request URI can be determined by examining the content of the local HTTP context after the request has been executed.
  
@@ -1569, +1616 @@

  
  = Advanced topics =
  
- == Stateful connections ==
- 
-   NTLM connections. SSL connections with client authentication.
- 
  == Custom client connections ==
  
+     In certain situations it may be necessary to customize the way HTTP messages get transmitted across the wire beyond what is possible possible using HTTP parameters in order to be able to deal non-standard, non-compliant behaviours. For instance, for web crawlers it may be necessary to force HttpClient into accepting malformed response heads in order to salvage the content of the messages. 
+     
+     Usually the process of plugging in a custom message parser or a custom connection implementation involves several steps:
+ 
+     * Provide a custom LineParser / LineFormatter interface implementation. Implement message parsing / formatting logic as required.
+ 
+ {{{
  class MyLineParser extends BasicLineParser {
  
  	@Override
@@ -1583, +1633 @@

  		try {
  			return super.parseHeader(buffer);
  		} catch (ParseException ex) {
+             // Suppress ParseException exception
  			return new BasicHeader("invalid", buffer.toString());
  		}
  	}
  	
  }
+ }}}
  
+     * Provide a custom OperatedClientConnection implementation. Replace default request / response parsers, request / response formatters with custom ones as required. Implement different message writing / reading code if necessary.
+ 
+ {{{    
  class MyClientConnection extends DefaultClientConnection {
  
  	@Override
@@ -1604, +1659 @@

  	}
  	
  }
+ }}}
  
+     * Provide a custom ClientConnectionOperator interface implementation in order to create connections of new class. Implement different socket initialization code if necessary.
+ 
+ {{{
  class MyClientConnectionOperator extends DefaultClientConnectionOperator {
  	
  	public MyClientConnectionOperator(final SchemeRegistry sr) {
@@ -1617, +1676 @@

  	}
  	
  }
+ }}}
  
+     * Provide a custom ClientConnectionManager interface implementation in order to create connection operator of new class.
+ 
+ {{{
  class MyClientConnManager extends SingleClientConnManager {
  	
      public MyClientConnManager(
@@ -1633, +1696 @@

  	}
  	
  }
+ }}}
  
+ == Stateful HTTP connections ==
+ 
+     While HTTP specification assumes that session state information is always embedded in HTTP messages in the form of HTTP cookies and therefore HTTP connections are always stateless, this assumption does not always hold true in real life. There are cases when HTTP connections are created with a particular user identity or within a particular security context and therefore cannot be shared with other users and can be reused by the same user only. Examples of such stateful HTTP connections are NTLM authenticated connections and SSL connections with client certificate authentication.
+ 
+ === User token handler ===
+     
+     HttpClient relies on UserTokenHandler interface to determine if the given execution context is user specific or not. The token object returned by this handler is expected to uniquely identify the current user if the context is user specific or to be 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 resources will not be shared with or reused by other users.
+ 
+     The default implementation of the UserTokenHandler interface uses an instance of Principal class to represent a state object for HTTP connections, if it can be obtained from the given execution context. DefaultUserTokenHandler will use the user principle of connection based authentication schemes such as NTLM or that of the SSL session with client authentication turned on. If both are unavailable, null token will be returned.   
+  
+     Users can provide a custom implementation if the default one does not satisfy their needs:
+     
+ {{{
+ DefaultHttpClient httpclient = new DefaultHttpClient();
+ httpclient.setUserTokenHandler(new UserTokenHandler() {
+ 
+ 	public Object getUserToken(HttpContext context) {
+ 		return context.getAttribute("my-token");
+ 	}
+ 	
+ });
+ }}} 
+ 
+ === User token and execution context ===
+ 
+     In the course of HTTP request execution HttpClient adds the following user identity related objects to the execution context: 
+ 
+     * '''http.user-token''' - Object instance representing the actual user identity, usually expected to be an instance of Principle interface.
+     
+     One can find out whether or not the connection used to execute the request was stateful by examining the content of the local HTTP context after the request has been executed.
+ 
+ {{{
+ DefaultHttpClient httpclient = new DefaultHttpClient();
+ HttpContext localContext = new BasicHttpContext();
+ HttpGet httpget = new HttpGet("http://localhost:8080/"); 
+ HttpResponse response = httpclient.execute(httpget, localContext);
+ HttpEntity entity = response.getEntity();
+ if (entity != null) {
+     entity.consumeContent();
+ }
+ Object userToken = localContext.getAttribute(ClientContext.USER_TOKEN);
+ System.out.println(userToken);
+ }}}    
+ 
+ === Persistent stateful connections ===
+ 
+     Please note that persistent connection that carry a state object can be reused only if the same state object is bound to the execution context when requests are executed. So, it is really important to ensure the either same context is reused for execution of subsequent HTTP requests by the same user or the user token is bound to the context prior to request execution.
+     
+ {{{
+ DefaultHttpClient httpclient = new DefaultHttpClient();
+ HttpContext localContext1 = new BasicHttpContext();
+ HttpGet httpget1 = new HttpGet("http://localhost:8080/"); 
+ HttpResponse response1 = httpclient.execute(httpget1, localContext1);
+ HttpEntity entity1 = response1.getEntity();
+ if (entity1 != null) {
+     entity1.consumeContent();
+ }
+ Principal principal = (Principal) localContext1.getAttribute(
+ 		ClientContext.USER_TOKEN);
+ 
+ HttpContext localContext2 = new BasicHttpContext();
+ localContext2.setAttribute(ClientContext.USER_TOKEN, principal);
+ HttpGet httpget2 = new HttpGet("http://localhost:8080/"); 
+ HttpResponse response2 = httpclient.execute(httpget2, localContext2);
+ HttpEntity entity2 = response2.getEntity();
+ if (entity2 != null) {
+     entity2.consumeContent();
+ }
+ }}}
+ 

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org