org.apache.hc.client5.http.nio

## Interface AsyncClientConnectionManager

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

      @Contract(threading=SAFE)
      public interface AsyncClientConnectionManager
      extends org.apache.hc.core5.io.ModalCloseable

  Represents a manager of persistent non-blocking 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:
    5.0

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `Future<AsyncConnectionEndpoint>` | `connect(AsyncConnectionEndpoint endpoint, org.apache.hc.core5.reactor.ConnectionInitiator connectionInitiator, org.apache.hc.core5.util.Timeout connectTimeout, Object attachment, org.apache.hc.core5.http.protocol.HttpContext context, org.apache.hc.core5.concurrent.FutureCallback<AsyncConnectionEndpoint> callback)` 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).
    `Future<AsyncConnectionEndpoint>` | `lease(String id, HttpRoute route, Object state, org.apache.hc.core5.util.Timeout requestTimeout, org.apache.hc.core5.concurrent.FutureCallback<AsyncConnectionEndpoint> callback)` Returns a `Future` object which can be used to obtain an `AsyncConnectionEndpoint` or to cancel the request by calling `Future.cancel(boolean)`.
    `void` | `release(AsyncConnectionEndpoint 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(AsyncConnectionEndpoint endpoint, Object attachment, org.apache.hc.core5.http.protocol.HttpContext context)` Upgrades transport security of the given endpoint by using the TLS security protocol.
    `default void` | `upgrade(AsyncConnectionEndpoint endpoint, Object attachment, org.apache.hc.core5.http.protocol.HttpContext context, org.apache.hc.core5.concurrent.FutureCallback<AsyncConnectionEndpoint> callback)` 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

          Future<AsyncConnectionEndpoint> lease(String id,
                                                HttpRoute route,
                                                Object state,
                                                org.apache.hc.core5.util.Timeout requestTimeout,
                                                org.apache.hc.core5.concurrent.FutureCallback<AsyncConnectionEndpoint> callback)

      Returns a `Future` object which can be used to obtain an `AsyncConnectionEndpoint` or to cancel the request by calling `Future.cancel(boolean)`.

      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(AsyncConnectionEndpoint, ConnectionInitiator, Timeout, Object, HttpContext, FutureCallback)` in order to connect directly to the target or to the first proxy hop, and optionally calling `upgrade(AsyncConnectionEndpoint, Object, 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.
        `state` - expected state of the connection or `null` if the connection is not expected to carry any state.
        `requestTimeout` - lease request timeout.
        `callback` - result callback.

    - #### release

          void release(AsyncConnectionEndpoint 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

          Future<AsyncConnectionEndpoint> connect(AsyncConnectionEndpoint endpoint,
                                                  org.apache.hc.core5.reactor.ConnectionInitiator connectionInitiator,
                                                  org.apache.hc.core5.util.Timeout connectTimeout,
                                                  Object attachment,
                                                  org.apache.hc.core5.http.protocol.HttpContext context,
                                                  org.apache.hc.core5.concurrent.FutureCallback<AsyncConnectionEndpoint> callback)

      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.
        `attachment` - connect request attachment.
        `callback` - result callback.

    - #### upgrade

          void upgrade(AsyncConnectionEndpoint endpoint,
                       Object attachment,
                       org.apache.hc.core5.http.protocol.HttpContext context)

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

    - #### upgrade

          default void upgrade(AsyncConnectionEndpoint endpoint,
                               Object attachment,
                               org.apache.hc.core5.http.protocol.HttpContext context,
                               org.apache.hc.core5.concurrent.FutureCallback<AsyncConnectionEndpoint> callback)

      Upgrades transport security of the given endpoint by using the TLS security protocol.
      Parameters:
        `endpoint` - the managed endpoint.
        `attachment` - the attachment the upgrade attachment object.
        `context` - the actual HTTP context.
        `callback` - result callback.
      Since:
        5.2

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