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: [email protected] For additional commands, e-mail: [email protected]
