The 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 the 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 implementations. 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. The DefaultHttpRoutePlanner implementation does not make use of any Java system properties, nor any system or browser proxy settings. It computes routes based exclusively on the HTTP parameters described below.

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.

PlainSocketFactory sf = PlainSocketFactory.getSocketFactory();
Socket socket = sf.createSocket();

HttpParams params = new BasicHttpParams();
params.setParameter(CoreConnectionPNames.CONNECTION_TIMEOUT, 1000L);
InetSocketAddress address = new InetSocketAddress("locahost", 8080);
sf.connectSocket(socket, address, null, params);

LayeredSchemeSocketFactory is an extension of the SchemeSocketFactory interface. Layered socket factories are capable of creating sockets layered over an existing plain socket. Socket layering is used primarily for creating secure sockets through proxies. HttpClient ships with SSLSocketFactory that implements SSL/TLS layering. Please note HttpClient does not use any custom encryption functionality. It is fully reliant on standard Java Cryptography (JCE) and Secure Sockets (JSEE) extensions.

HttpClient makes use of SSLSocketFactory to create SSL connections. SSLSocketFactory allows for a high degree of customization. It can take an instance of javax.net.ssl.SSLContext as a parameter and use it to create custom configured SSL connections.

TrustManager easyTrustManager = new X509TrustManager() {

    @Override
    public void checkClientTrusted(
            X509Certificate[] chain,
            String authType) throws CertificateException {
        // Oh, I am easy!
    }

    @Override
    public void checkServerTrusted(
            X509Certificate[] chain,
            String authType) throws CertificateException {
        // Oh, I am easy!
    }

    @Override
    public X509Certificate[] getAcceptedIssuers() {
        return null;
    }
    
};

SSLContext sslcontext = SSLContext.getInstance("TLS");
sslcontext.init(null, new TrustManager[] { easyTrustManager }, null);

SSLSocketFactory sf = new SSLSocketFactory(sslcontext); 
SSLSocket socket = (SSLSocket) sf.createSocket();
socket.setEnabledCipherSuites(new String[] { "SSL_RSA_WITH_RC4_128_MD5" });

HttpParams params = new BasicHttpParams();
params.setParameter(CoreConnectionPNames.CONNECTION_TIMEOUT, 1000L);
InetSocketAddress address = new InetSocketAddress("locahost", 443);
sf.connectSocket(socket, address, null, params);

Customization of SSLSocketFactory implies a certain degree of familiarity with the concepts of the SSL/TLS protocol, a detailed explanation of which is out of scope for this document. Please refer to the Java Secure Socket Extension for a detailed description of javax.net.ssl.SSLContext and related tools.

In addition to the trust verification and the client authentication performed on the SSL/TLS protocol level, HttpClient can optionally verify whether the target hostname matches the names stored inside the server's X.509 certificate, once the connection has been established. This verification can provide additional guarantees of authenticity of the server trust material. The X509HostnameVerifier interface represents a strategy for hostname verification. HttpClient ships with three X509HostnameVerifier implementations. Important: hostname verification should not be confused with SSL trust verification.

Per default HttpClient uses the BrowserCompatHostnameVerifier implementation. One can specify a different hostname verifier implementation if desired

SSLSocketFactory sf = new SSLSocketFactory(
    SSLContext.getInstance("TLS"),
    SSLSocketFactory.STRICT_HOSTNAME_VERIFIER);

Operated connections are client side connections whose underlying socket or state can be manipulated by an external entity, usually referred to as a connection operator. The OperatedClientConnection interface extends the HttpClientConnection interface and defines additional methods to manage connection sockets. The ClientConnectionOperator interface represents a strategy for creating OperatedClientConnection instances and updating the underlying socket of those objects. Implementations will most likely make use a SchemeSocketFactory to create java.net.Socket instances. The ClientConnectionOperator interface enables users of HttpClient to provide a custom strategy for connection operators as well as the ability to provide an alternative implementation of the OperatedClientConnection interface.

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 return 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 the 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 returned 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 a connection manager:

Scheme http = new Scheme("http", 80, PlainSocketFactory.getSocketFactory());
SchemeRegistry sr = new SchemeRegistry();
sr.register(http);
ClientConnectionManager connMrg = new SingleClientConnManager(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;
}

SingleClientConnManager is a simple connection manager that maintains only one connection at a time. Even though this class is thread-safe it ought to be used by one execution thread only. SingleClientConnManager will make an effort to reuse the connection for subsequent requests with the same route. It will, however, close the existing connection and re-open it for the given route, if the route of the persistent connection does not match that of the connection request. If the connection has been already been allocated, then java.lang.IllegalStateException is thrown.

SingleClientConnManager is used by HttpClient per default.

ThreadSafeClientConnManager is a more complex implementation that manages a pool of client connections and is able to service connection requests from multiple execution threads. Connections are pooled on a per route basis. A request for a route for which the manager already has a persistent connection available in the pool will be serviced by leasing a connection from the pool rather than creating a brand new connection.

ThreadSafeClientConnManager maintains a maximum limit of connections on a per route basis and in total. Per default this implementation will create no more than 2 concurrent connections per given route and no more 20 connections in total. For many real-world applications these limits may prove too constraining, especially if they use HTTP as a transport protocol for their services. Connection limits can be adjusted using the appropriate HTTP parameters.

This example shows how the connection pool parameters can be adjusted:

SchemeRegistry schemeRegistry = new SchemeRegistry();
schemeRegistry.register(
         new Scheme("http", 80, PlainSocketFactory.getSocketFactory()));
schemeRegistry.register(
         new Scheme("https", 443, SSLSocketFactory.getSocketFactory()));

ThreadSafeClientConnManager cm = new ThreadSafeClientConnManager(schemeRegistry);
// Increase max total connection to 200
cm.setMaxTotalConnections(200);
// Increase default max connection per route to 20
cm.setDefaultMaxPerRoute(20);
// Increase max connections for localhost:80 to 50
HttpHost localhost = new HttpHost("locahost", 80);
cm.setMaxForRoute(new HttpRoute(localhost), 50);
 
HttpClient httpClient = new DefaultHttpClient(cm);

When an HttpClient instance is no longer needed and is about to go out of scope it is important to shut down its connection manager to ensure that all connections kept alive by the manager get closed and system resources allocated by those connections are released.

DefaultHttpClient httpclient = new DefaultHttpClient();
HttpGet httpget = new HttpGet("http://www.google.com/");
HttpResponse response = httpclient.execute(httpget);
HttpEntity entity = response.getEntity();
System.out.println(response.getStatusLine());
EntityUtils.consume(entity);
httpclient.getConnectionManager().shutdown();