org.apache.http.impl.conn

## Class PoolingHttpClientConnectionManager

- java.lang.Object
- - org.apache.http.impl.conn.PoolingHttpClientConnectionManager

- All Implemented Interfaces:
    Closeable, AutoCloseable, HttpClientConnectionManager, org.apache.http.pool.ConnPoolControl<HttpRoute>

      @Contract(threading=SAFE_CONDITIONAL)
      public class PoolingHttpClientConnectionManager
      extends Object
      implements HttpClientConnectionManager, org.apache.http.pool.ConnPoolControl<HttpRoute>, Closeable

  `ClientConnectionPoolManager` maintains a pool of `HttpClientConnection`s and is able to service connection requests from multiple execution threads. Connections are pooled on a per route basis. A request for a route which already the manager has persistent connections for available in the pool will be services by leasing a connection from the pool rather than creating a brand new connection.

  `ClientConnectionPoolManager` maintains a maximum limit of connection on a per route basis and in total. Per default this implementation will create no more than 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, however, can be adjusted using `ConnPoolControl` methods.

  Total time to live (TTL) set at construction time defines maximum life span of persistent connections regardless of their expiration setting. No persistent connection will be re-used past its TTL value.

  The handling of stale connections was changed in version 4.4. Previously, the code would check every connection by default before re-using it. The code now only checks the connection if the elapsed time since the last use of the connection exceeds the timeout that has been set. The default timeout is set to 2000ms

  Since:
    4.3

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `PoolingHttpClientConnectionManager()`
    `PoolingHttpClientConnectionManager(HttpClientConnectionOperator httpClientConnectionOperator, HttpConnectionFactory<HttpRoute,ManagedHttpClientConnection> connFactory, long timeToLive, TimeUnit timeUnit)`
    `PoolingHttpClientConnectionManager(HttpConnectionFactory<HttpRoute,ManagedHttpClientConnection> connFactory)`
    `PoolingHttpClientConnectionManager(long timeToLive, TimeUnit timeUnit)`
    `PoolingHttpClientConnectionManager(org.apache.http.config.Registry<ConnectionSocketFactory> socketFactoryRegistry)`
    `PoolingHttpClientConnectionManager(org.apache.http.config.Registry<ConnectionSocketFactory> socketFactoryRegistry, DnsResolver dnsResolver)`
    `PoolingHttpClientConnectionManager(org.apache.http.config.Registry<ConnectionSocketFactory> socketFactoryRegistry, HttpConnectionFactory<HttpRoute,ManagedHttpClientConnection> connFactory)`
    `PoolingHttpClientConnectionManager(org.apache.http.config.Registry<ConnectionSocketFactory> socketFactoryRegistry, HttpConnectionFactory<HttpRoute,ManagedHttpClientConnection> connFactory, DnsResolver dnsResolver)`
    `PoolingHttpClientConnectionManager(org.apache.http.config.Registry<ConnectionSocketFactory> socketFactoryRegistry, HttpConnectionFactory<HttpRoute,ManagedHttpClientConnection> connFactory, SchemePortResolver schemePortResolver, DnsResolver dnsResolver, long timeToLive, TimeUnit timeUnit)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()`
    `void` | `closeExpiredConnections()` Closes all expired connections in the pool.
    `void` | `closeIdleConnections(long idleTimeout, TimeUnit timeUnit)` Closes idle connections in the pool.
    `void` | `connect(org.apache.http.HttpClientConnection managedConn, HttpRoute route, int connectTimeout, org.apache.http.protocol.HttpContext context)` Connects the underlying connection socket to the connection target in case of a direct route or to the first proxy hop in case of a route via a proxy (or multiple proxies).
    `protected void` | `enumAvailable(org.apache.http.pool.PoolEntryCallback<HttpRoute,ManagedHttpClientConnection> callback)`
    `protected void` | `enumLeased(org.apache.http.pool.PoolEntryCallback<HttpRoute,ManagedHttpClientConnection> callback)`
    `protected void` | `finalize()`
    `org.apache.http.config.ConnectionConfig` | `getConnectionConfig(org.apache.http.HttpHost host)`
    `org.apache.http.config.ConnectionConfig` | `getDefaultConnectionConfig()`
    `int` | `getDefaultMaxPerRoute()`
    `org.apache.http.config.SocketConfig` | `getDefaultSocketConfig()`
    `int` | `getMaxPerRoute(HttpRoute route)`
    `int` | `getMaxTotal()`
    `Set<HttpRoute>` | `getRoutes()`
    `org.apache.http.config.SocketConfig` | `getSocketConfig(org.apache.http.HttpHost host)`
    `org.apache.http.pool.PoolStats` | `getStats(HttpRoute route)`
    `org.apache.http.pool.PoolStats` | `getTotalStats()`
    `int` | `getValidateAfterInactivity()`
    `protected org.apache.http.HttpClientConnection` | `leaseConnection(Future<org.apache.http.impl.conn.CPoolEntry> future, long timeout, TimeUnit timeUnit)`
    `void` | `releaseConnection(org.apache.http.HttpClientConnection managedConn, Object state, long keepalive, TimeUnit timeUnit)` Releases the connection back to the manager making it potentially re-usable by other consumers.
    `ConnectionRequest` | `requestConnection(HttpRoute route, Object state)` Returns a new `ConnectionRequest`, from which a `HttpClientConnection` can be obtained or the request can be aborted.
    `void` | `routeComplete(org.apache.http.HttpClientConnection managedConn, HttpRoute route, org.apache.http.protocol.HttpContext context)` Marks the connection as fully established with all its intermediate hops completed.
    `void` | `setConnectionConfig(org.apache.http.HttpHost host, org.apache.http.config.ConnectionConfig connectionConfig)`
    `void` | `setDefaultConnectionConfig(org.apache.http.config.ConnectionConfig defaultConnectionConfig)`
    `void` | `setDefaultMaxPerRoute(int max)`
    `void` | `setDefaultSocketConfig(org.apache.http.config.SocketConfig defaultSocketConfig)`
    `void` | `setMaxPerRoute(HttpRoute route, int max)`
    `void` | `setMaxTotal(int max)`
    `void` | `setSocketConfig(org.apache.http.HttpHost host, org.apache.http.config.SocketConfig socketConfig)`
    `void` | `setValidateAfterInactivity(int ms)` Defines period of inactivity in milliseconds after which persistent connections must be re-validated prior to being `leased` to the consumer.
    `void` | `shutdown()` Shuts down this connection manager and releases allocated resources.
    `void` | `upgrade(org.apache.http.HttpClientConnection managedConn, HttpRoute route, org.apache.http.protocol.HttpContext context)` Upgrades the underlying connection socket to TLS/SSL (or another layering protocol) after having executed `CONNECT` method to all intermediate proxy hops

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### PoolingHttpClientConnectionManager

          public PoolingHttpClientConnectionManager()

    - #### PoolingHttpClientConnectionManager

          public PoolingHttpClientConnectionManager(long timeToLive,
                                            TimeUnit timeUnit)

    - #### PoolingHttpClientConnectionManager

          public PoolingHttpClientConnectionManager(org.apache.http.config.Registry<ConnectionSocketFactory> socketFactoryRegistry)

    - #### PoolingHttpClientConnectionManager

          public PoolingHttpClientConnectionManager(org.apache.http.config.Registry<ConnectionSocketFactory> socketFactoryRegistry,
                                            DnsResolver dnsResolver)

    - #### PoolingHttpClientConnectionManager

          public PoolingHttpClientConnectionManager(org.apache.http.config.Registry<ConnectionSocketFactory> socketFactoryRegistry,
                                            HttpConnectionFactory<HttpRoute,ManagedHttpClientConnection> connFactory)

    - #### PoolingHttpClientConnectionManager

          public PoolingHttpClientConnectionManager(HttpConnectionFactory<HttpRoute,ManagedHttpClientConnection> connFactory)

    - #### PoolingHttpClientConnectionManager

          public PoolingHttpClientConnectionManager(org.apache.http.config.Registry<ConnectionSocketFactory> socketFactoryRegistry,
                                            HttpConnectionFactory<HttpRoute,ManagedHttpClientConnection> connFactory,
                                            DnsResolver dnsResolver)

    - #### PoolingHttpClientConnectionManager

          public PoolingHttpClientConnectionManager(org.apache.http.config.Registry<ConnectionSocketFactory> socketFactoryRegistry,
                                            HttpConnectionFactory<HttpRoute,ManagedHttpClientConnection> connFactory,
                                            SchemePortResolver schemePortResolver,
                                            DnsResolver dnsResolver,
                                            long timeToLive,
                                            TimeUnit timeUnit)

    - #### PoolingHttpClientConnectionManager

          public PoolingHttpClientConnectionManager(HttpClientConnectionOperator httpClientConnectionOperator,
                                            HttpConnectionFactory<HttpRoute,ManagedHttpClientConnection> connFactory,
                                            long timeToLive,
                                            TimeUnit timeUnit)

      Since:
        4.4

  - ### Method Detail

    - #### finalize

          protected void finalize()
                           throws Throwable

      Overrides:
        `finalize` in class `Object`
      Throws:
        `Throwable`

    - #### close

          public void close()

      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`

    - #### requestConnection

          public ConnectionRequest requestConnection(HttpRoute route,
                                            Object state)

      Description copied from interface: `HttpClientConnectionManager`
      Returns a new `ConnectionRequest`, from which a `HttpClientConnection` can be obtained or the request can be aborted.

      Please note that newly allocated connections can be returned in the closed state. The consumer of that connection is responsible for fully establishing the route the to the connection target by calling `connect` in order to connect directly to the target or to the first proxy hop, optionally calling `upgrade` method to upgrade the connection after having executed `CONNECT` method to all intermediate proxy hops and and finally calling `routeComplete` to mark the route as fully completed.

      Specified by:
        `requestConnection` in interface `HttpClientConnectionManager`
      Parameters:
        `route` - HTTP route of the requested connection.
        `state` - expected state of the connection or `null` if the connection is not expected to carry any state.

    - #### leaseConnection

          protected org.apache.http.HttpClientConnection leaseConnection(Future<org.apache.http.impl.conn.CPoolEntry> future,
                                                             long timeout,
                                                             TimeUnit timeUnit)
                                                                  throws InterruptedException,
                                                                         ExecutionException,
                                                                         ConnectionPoolTimeoutException

      Throws:
        `InterruptedException`
        `ExecutionException`
        `ConnectionPoolTimeoutException`

    - #### releaseConnection

          public void releaseConnection(org.apache.http.HttpClientConnection managedConn,
                               Object state,
                               long keepalive,
                               TimeUnit timeUnit)

      Description copied from interface: `HttpClientConnectionManager`
      Releases the connection back to the manager making it potentially re-usable by other consumers. Optionally, the maximum period of how long the manager should keep the connection alive can be defined using `validDuration` and `timeUnit` parameters.
      Specified by:
        `releaseConnection` in interface `HttpClientConnectionManager`
      Parameters:
        `managedConn` - the managed connection to release.
        `keepalive` - the duration of time this connection is valid for reuse.
        `timeUnit` - the time unit.
      See Also:
        `HttpClientConnectionManager.closeExpiredConnections()`

    - #### connect

          public void connect(org.apache.http.HttpClientConnection managedConn,
                     HttpRoute route,
                     int connectTimeout,
                     org.apache.http.protocol.HttpContext context)
                       throws IOException

      Description copied from interface: `HttpClientConnectionManager`
      Connects the underlying connection socket to the connection target in case of a direct route or to the first proxy hop in case of a route via a proxy (or multiple proxies).
      Specified by:
        `connect` in interface `HttpClientConnectionManager`
      Parameters:
        `managedConn` - the managed connection.
        `route` - the route of the connection.
        `connectTimeout` - connect timeout in milliseconds.
        `context` - the actual HTTP context.
      Throws:
        `IOException`

    - #### upgrade

          public void upgrade(org.apache.http.HttpClientConnection managedConn,
                     HttpRoute route,
                     org.apache.http.protocol.HttpContext context)
                       throws IOException

      Description copied from interface: `HttpClientConnectionManager`
      Upgrades the underlying connection socket to TLS/SSL (or another layering protocol) after having executed `CONNECT` method to all intermediate proxy hops
      Specified by:
        `upgrade` in interface `HttpClientConnectionManager`
      Parameters:
        `managedConn` - the managed connection.
        `route` - the route of the connection.
        `context` - the actual HTTP context.
      Throws:
        `IOException`

    - #### routeComplete

          public void routeComplete(org.apache.http.HttpClientConnection managedConn,
                           HttpRoute route,
                           org.apache.http.protocol.HttpContext context)
                             throws IOException

      Description copied from interface: `HttpClientConnectionManager`
      Marks the connection as fully established with all its intermediate hops completed.
      Specified by:
        `routeComplete` in interface `HttpClientConnectionManager`
      Parameters:
        `managedConn` - the managed connection.
        `route` - the route of the connection.
        `context` - the actual HTTP context.
      Throws:
        `IOException`

    - #### shutdown

          public void shutdown()

      Description copied from interface: `HttpClientConnectionManager`
      Shuts down this connection manager and releases allocated resources. This includes closing all connections, whether they are currently used or not.
      Specified by:
        `shutdown` in interface `HttpClientConnectionManager`

    - #### closeIdleConnections

          public void closeIdleConnections(long idleTimeout,
                                  TimeUnit timeUnit)

      Description copied from interface: `HttpClientConnectionManager`
      Closes idle connections in the pool.

      Open connections in the pool that have not been used for the timespan given by the argument will be closed. Currently allocated connections are not subject to this method. Times will be checked with milliseconds precision

      All expired connections will also be closed.

      Specified by:
        `closeIdleConnections` in interface `HttpClientConnectionManager`
      Parameters:
        `idleTimeout` - the idle time of connections to be closed
        `timeUnit` - the unit for the `idletime`
      See Also:
        `HttpClientConnectionManager.closeExpiredConnections()`

    - #### closeExpiredConnections

          public void closeExpiredConnections()

      Description copied from interface: `HttpClientConnectionManager`
      Closes all expired connections in the pool.

      Open connections in the pool that have not been used for the timespan defined when the connection was released will be closed. Currently allocated connections are not subject to this method. Times will be checked with milliseconds precision.

      Specified by:
        `closeExpiredConnections` in interface `HttpClientConnectionManager`

    - #### enumAvailable

          protected void enumAvailable(org.apache.http.pool.PoolEntryCallback<HttpRoute,ManagedHttpClientConnection> callback)

    - #### enumLeased

          protected void enumLeased(org.apache.http.pool.PoolEntryCallback<HttpRoute,ManagedHttpClientConnection> callback)

    - #### getMaxTotal

          public int getMaxTotal()

      Specified by:
        `getMaxTotal` in interface `org.apache.http.pool.ConnPoolControl<HttpRoute>`

    - #### setMaxTotal

          public void setMaxTotal(int max)

      Specified by:
        `setMaxTotal` in interface `org.apache.http.pool.ConnPoolControl<HttpRoute>`

    - #### getDefaultMaxPerRoute

          public int getDefaultMaxPerRoute()

      Specified by:
        `getDefaultMaxPerRoute` in interface `org.apache.http.pool.ConnPoolControl<HttpRoute>`

    - #### setDefaultMaxPerRoute

          public void setDefaultMaxPerRoute(int max)

      Specified by:
        `setDefaultMaxPerRoute` in interface `org.apache.http.pool.ConnPoolControl<HttpRoute>`

    - #### getMaxPerRoute

          public int getMaxPerRoute(HttpRoute route)

      Specified by:
        `getMaxPerRoute` in interface `org.apache.http.pool.ConnPoolControl<HttpRoute>`

    - #### setMaxPerRoute

          public void setMaxPerRoute(HttpRoute route,
                            int max)

      Specified by:
        `setMaxPerRoute` in interface `org.apache.http.pool.ConnPoolControl<HttpRoute>`

    - #### getTotalStats

          public org.apache.http.pool.PoolStats getTotalStats()

      Specified by:
        `getTotalStats` in interface `org.apache.http.pool.ConnPoolControl<HttpRoute>`

    - #### getStats

          public org.apache.http.pool.PoolStats getStats(HttpRoute route)

      Specified by:
        `getStats` in interface `org.apache.http.pool.ConnPoolControl<HttpRoute>`

    - #### getRoutes

          public Set<HttpRoute> getRoutes()

      Since:
        4.4

    - #### getDefaultSocketConfig

          public org.apache.http.config.SocketConfig getDefaultSocketConfig()

    - #### setDefaultSocketConfig

          public void setDefaultSocketConfig(org.apache.http.config.SocketConfig defaultSocketConfig)

    - #### getDefaultConnectionConfig

          public org.apache.http.config.ConnectionConfig getDefaultConnectionConfig()

    - #### setDefaultConnectionConfig

          public void setDefaultConnectionConfig(org.apache.http.config.ConnectionConfig defaultConnectionConfig)

    - #### getSocketConfig

          public org.apache.http.config.SocketConfig getSocketConfig(org.apache.http.HttpHost host)

    - #### setSocketConfig

          public void setSocketConfig(org.apache.http.HttpHost host,
                             org.apache.http.config.SocketConfig socketConfig)

    - #### getConnectionConfig

          public org.apache.http.config.ConnectionConfig getConnectionConfig(org.apache.http.HttpHost host)

    - #### setConnectionConfig

          public void setConnectionConfig(org.apache.http.HttpHost host,
                                 org.apache.http.config.ConnectionConfig connectionConfig)

    - #### getValidateAfterInactivity

          public int getValidateAfterInactivity()

      Since:
        4.4
      See Also:
        `setValidateAfterInactivity(int)`

    - #### setValidateAfterInactivity

          public void setValidateAfterInactivity(int ms)

      Defines period of inactivity in milliseconds after which persistent connections must be re-validated prior to being `leased` to the consumer. Non-positive value passed to this method disables connection validation. This check helps detect connections that have become stale (half-closed) while kept inactive in the pool.
      Since:
        4.4
      See Also:
        `leaseConnection(java.util.concurrent.Future, long, java.util.concurrent.TimeUnit)`

Copyright © 1999–2022 The Apache Software Foundation. All rights reserved.