org.apache.http.conn

## Interface HttpClientConnectionManager

- All Known Implementing Classes:
    BasicHttpClientConnectionManager, PoolingHttpClientConnectionManager

      public interface HttpClientConnectionManager

  Represents a manager of persistent client connections.

  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 of execution can have access to a connection at a time.

  Implementations of this interface must be thread-safe. Access to shared data must be synchronized as methods of this interface may be executed from multiple threads.

  Since:
    4.3

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `closeExpiredConnections()` Closes all expired connections in the pool.
    `void` | `closeIdleConnections(long idletime, TimeUnit timeUnit)` Closes idle connections in the pool.
    `void` | `connect(org.apache.http.HttpClientConnection conn, 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).
    `void` | `releaseConnection(org.apache.http.HttpClientConnection conn, Object newState, long validDuration, 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 conn, HttpRoute route, org.apache.http.protocol.HttpContext context)` Marks the connection as fully established with all its intermediate hops completed.
    `void` | `shutdown()` Shuts down this connection manager and releases allocated resources.
    `void` | `upgrade(org.apache.http.HttpClientConnection conn, 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

- - ### Method Detail

    - #### requestConnection

          ConnectionRequest requestConnection(HttpRoute route,
                                            Object state)

      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.

      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.

    - #### releaseConnection

          void releaseConnection(org.apache.http.HttpClientConnection conn,
                               Object newState,
                               long validDuration,
                               TimeUnit timeUnit)

      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.
      Parameters:
        `conn` - the managed connection to release.
        `validDuration` - the duration of time this connection is valid for reuse.
        `timeUnit` - the time unit.
      See Also:
        `closeExpiredConnections()`

    - #### connect

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

      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).
      Parameters:
        `conn` - the managed connection.
        `route` - the route of the connection.
        `connectTimeout` - connect timeout in milliseconds.
        `context` - the actual HTTP context.
      Throws:
        `IOException`

    - #### upgrade

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

      Upgrades the underlying connection socket to TLS/SSL (or another layering protocol) after having executed `CONNECT` method to all intermediate proxy hops
      Parameters:
        `conn` - the managed connection.
        `route` - the route of the connection.
        `context` - the actual HTTP context.
      Throws:
        `IOException`

    - #### routeComplete

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

      Marks the connection as fully established with all its intermediate hops completed.
      Parameters:
        `conn` - the managed connection.
        `route` - the route of the connection.
        `context` - the actual HTTP context.
      Throws:
        `IOException`

    - #### closeIdleConnections

          void closeIdleConnections(long idletime,
                                  TimeUnit timeUnit)

      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.

      Parameters:
        `idletime` - the idle time of connections to be closed
        `timeUnit` - the unit for the `idletime`
      See Also:
        `closeExpiredConnections()`

    - #### closeExpiredConnections

          void closeExpiredConnections()

      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.

    - #### shutdown

          void shutdown()

      Shuts down this connection manager and releases allocated resources. This includes closing all connections, whether they are currently used or not.

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