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 Mon, 20 Apr 2009 17:19:07 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

------------------------------------------------------------------------------
  });
  }}}
  
- == Managed connections ==
+ == HTTP connection managers ==
  
-   Connection operators. Managed connections and entities. Connection requests.
+ === Connection operators ===
+ 
+     Operated connections are client side connections whose underlying socket or its state
can be manipulated by an external entity, usually referred to as a connection operator. OperatedClientConnection
interface extends HttpClientConnection interface and define additional methods to manage connection
socket.  The ClientConnectionOperator interface represents a strategy for creating OperatedClientConnection
instances and updating the underlying Socket of those objects. Implementations will most likely
make use SocketFactorys to create Socket instances. The ClientConnectionOperator interface
enables the users of HttpClient to provide a custom strategy for connection operators as well
as an ability to provide alternative implementation of the OperatedClientConnection interface.
+ 
+ === Managed connections and connection managers ===
+ 
+     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.
+ 
+     This is an example of acquiring a connection from the connection manager:  
+     
+ {{{
+ HttpParams params = new BasicHttpParams();
+ Scheme http = new Scheme("http", PlainSocketFactory.getSocketFactory(), 80);
+ SchemeRegistry sr = new SchemeRegistry();
+ sr.register(http);
+ 
+ ClientConnectionManager connMrg = new SingleClientConnManager(params, sr);
+ 
+ // Request new connection. This can be a long process
+ ClientConnectionRequest connRequest = connMrg.requestConnection(
+         new HttpRoute(new HttpHost("localhost", 80)), null);
+ 
+ // Wait for connection up to 10 sec
+ ManagedClientConnection conn = connRequest.getConnection(10, TimeUnit.SECONDS);
+ try {
+     // Do useful things with the connection.
+     // Release it when done.
+     conn.releaseConnection();
+ } catch (IOException ex) {
+     // Abort connection upon an I/O error.
+     conn.abortConnection();
+     throw ex;
+ }
+ }}}
+     
+     The connection request can be terminated prematurely by calling ClientConnectionRequest#abortRequest()
if necessary. This will unblock the thread blocked in the ClientConnectionRequest#getConnection()
method.
+ 
+     BasicManagedEntity wrapper class can be used to ensure automatic release of the underlying
connection once the response content has been fully consumed. HttpClient uses this mechanism
internally to achieve transparent connection release for all responses obtained from HttpClient#execute
methods:
+     
+ {{{
+ ClientConnectionRequest connRequest = connMrg.requestConnection(
+         new HttpRoute(new HttpHost("localhost", 80)), null);
+ ManagedClientConnection conn = connRequest.getConnection(10, TimeUnit.SECONDS);
+ try {
+     BasicHttpRequest request = new BasicHttpRequest("GET", "/");
+     conn.sendRequestHeader(request);
+     HttpResponse response = conn.receiveResponseHeader();
+     conn.receiveResponseEntity(response);
+     HttpEntity entity = response.getEntity();
+     if (entity != null) {
+         BasicManagedEntity managedEntity = new BasicManagedEntity(entity, conn, true);
+         // Replace entity
+         response.setEntity(managedEntity);
+     }
+     // Do something useful with the response
+     // The connection will be released automatically 
+     // as soon as the response content has been consumed
+ } catch (IOException ex) {
+     // Abort connection upon an I/O error.
+     conn.abortConnection();
+     throw ex;
+ }
+ }}}
-   
+    
  === Simple connection manager ===
  
    One connection per client. 
@@ -938, +1002 @@

  
    Custom redirect handling.
  
- = Advanced topics =
- 
- == Stateful connections ==
- 
-   Pooling stateful connections. User tokens. 
- 
- === User token handler ===
-   
-   Custom user token handling.
-   
- == DNS name resolution ==
- 
-   Custom DNS name resolution.
- 
- == Custom HTTP connections ==
- 
-   Replacing the standard HTTP connection implementation with a custom one.
- 

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


Mime
View raw message