hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Httpcomponents Wiki] Update of "HttpClientTutorial" by OlegKalnichevski
Date Thu, 04 Jun 2009 18:20:11 GMT
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


Mime
View raw message