org.apache.hc.client5.http.io

## Interface HttpClientConnectionManager

- All Superinterfaces:
    AutoCloseable, Closeable, org.apache.hc.core5.io.ModalCloseable
  All Known Implementing Classes:
    BasicHttpClientConnectionManager, PoolingHttpClientConnectionManager

      public interface HttpClientConnectionManager
      extends org.apache.hc.core5.io.ModalCloseable

  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` | `connect(ConnectionEndpoint endpoint, org.apache.hc.core5.util.TimeValue connectTimeout, org.apache.hc.core5.http.protocol.HttpContext context)` Connects the endpoint to the initial hop (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).
    `LeaseRequest` | `lease(String id, HttpRoute route, org.apache.hc.core5.util.Timeout requestTimeout, Object state)` Returns a `LeaseRequest` object which can be used to obtain a `ConnectionEndpoint` to cancel the request by calling `Cancellable.cancel()`.
    `void` | `release(ConnectionEndpoint endpoint, Object newState, org.apache.hc.core5.util.TimeValue validDuration)` Releases the endpoint back to the manager making it potentially re-usable by other consumers.
    `void` | `upgrade(ConnectionEndpoint endpoint, org.apache.hc.core5.http.protocol.HttpContext context)` Upgrades transport security of the given endpoint by using the TLS security protocol.

    - ### Methods inherited from interface org.apache.hc.core5.io.ModalCloseable

      `close`

    - ### Methods inherited from interface java.io.Closeable

      `close`

- - ### Method Detail

    - #### lease

          LeaseRequest lease(String id,
                           HttpRoute route,
                           org.apache.hc.core5.util.Timeout requestTimeout,
                           Object state)

      Returns a `LeaseRequest` object which can be used to obtain a `ConnectionEndpoint` to cancel the request by calling `Cancellable.cancel()`.

      Please note that newly allocated endpoints can be leased `disconnected`. The consumer of the endpoint is responsible for fully establishing the route to the endpoint target by calling `connect(ConnectionEndpoint, TimeValue, HttpContext)` in order to connect directly to the target or to the first proxy hop, and optionally calling `upgrade(ConnectionEndpoint, HttpContext)` method to upgrade the underlying transport to Transport Layer Security after having executed a `CONNECT` method to all intermediate proxy hops.

      Parameters:
        `id` - unique operation ID or `null`.
        `route` - HTTP route of the requested connection.
        `requestTimeout` - lease request timeout.
        `state` - expected state of the connection or `null` if the connection is not expected to carry any state.
      Since:
        5.0

    - #### release

          void release(ConnectionEndpoint endpoint,
                     Object newState,
                     org.apache.hc.core5.util.TimeValue validDuration)

      Releases the endpoint 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:
        `endpoint` - the managed endpoint.
        `newState` - the new connection state of `null` if state-less.
        `validDuration` - the duration of time this connection is valid for reuse.

    - #### connect

          void connect(ConnectionEndpoint endpoint,
                     org.apache.hc.core5.util.TimeValue connectTimeout,
                     org.apache.hc.core5.http.protocol.HttpContext context)
                       throws IOException

      Connects the endpoint to the initial hop (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:
        `endpoint` - the managed endpoint.
        `connectTimeout` - connect timeout.
        `context` - the actual HTTP context.
      Throws:
        `IOException`

    - #### upgrade

          void upgrade(ConnectionEndpoint endpoint,
                     org.apache.hc.core5.http.protocol.HttpContext context)
                       throws IOException

      Upgrades transport security of the given endpoint by using the TLS security protocol.
      Parameters:
        `endpoint` - the managed endpoint.
        `context` - the actual HTTP context.
      Throws:
        `IOException`

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