org.apache.hc.client5.http.async

## Interface AsyncExecRuntime

    @Internal
    public interface AsyncExecRuntime

Execution runtime that provides access to the underlying connection endpoint and helps manager its life cycle.

This interface is considered internal and generally ought not be used or accessed by custom request exec handlers.

Since:
  5.0

### Method Summary

All Methods Instance Methods Abstract Methods Default Methods
`org.apache.hc.core5.concurrent.Cancellable` `acquireEndpoint(String id, HttpRoute route, Object state, HttpClientContext context, org.apache.hc.core5.concurrent.FutureCallback<AsyncExecRuntime> callback)` Initiates operation to acquire a connection endpoint.
`org.apache.hc.core5.concurrent.Cancellable` `connectEndpoint(HttpClientContext context, org.apache.hc.core5.concurrent.FutureCallback<AsyncExecRuntime> callback)` Initiates operation to connect the local 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).
`void` `discardEndpoint()` Shuts down and discards the acquired endpoint.
`void` `disconnectEndpoint()` Disconnects the local endpoint from the initial hop in the connection route.
`org.apache.hc.core5.concurrent.Cancellable` `execute(String id, org.apache.hc.core5.http.nio.AsyncClientExchangeHandler exchangeHandler, HttpClientContext context)` Initiates a message exchange using the given handler.
`AsyncExecRuntime` `fork()` Forks this runtime for parallel execution.
`default EndpointInfo` `getEndpointInfo()` Returns information about the underlying endpoint when connected or `null` otherwise.
`boolean` `isEndpointAcquired()` Determines of a connection endpoint has been acquired.
`boolean` `isEndpointConnected()` Determines of there the endpoint is connected 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).
`void` `markConnectionNonReusable()` Marks the connection as non re-usable.
`void` `markConnectionReusable(Object state, org.apache.hc.core5.util.TimeValue validityTime)` Marks the connection as potentially re-usable for the given period of time and also marks it as stateful if the state representation is given.
`void` `releaseEndpoint()` Releases the acquired endpoint potentially making it available for re-use.
`void` `upgradeTls(HttpClientContext context)` Upgrades transport security of the active connection by using the TLS security protocol.
`default void` `upgradeTls(HttpClientContext context, org.apache.hc.core5.concurrent.FutureCallback<AsyncExecRuntime> callback)` Upgrades transport security of the active connection by using the TLS security protocol.
`boolean` `validateConnection()` Validates the connection making sure it can be used to execute requests.

### Method Detail

#### isEndpointAcquired

    boolean isEndpointAcquired()

Determines of a connection endpoint has been acquired.

Returns:
  `true` if an endpoint has been acquired, `false` otherwise.

#### acquireEndpoint

    org.apache.hc.core5.concurrent.Cancellable acquireEndpoint(String id,
                                                               HttpRoute route,
                                                               Object state,
                                                               HttpClientContext context,
                                                               org.apache.hc.core5.concurrent.FutureCallback<AsyncExecRuntime> callback)

Initiates operation to acquire a connection endpoint. Endpoints can leased from a pool or unconnected new endpoint can be created.

Parameters:
  `id` - unique operation ID or `null`.
  `route` - the connection route.
  `state` - the expected connection state. May be `null` if connection can be state-less or its state is irrelevant.
  `context` - the execution context.
  `callback` - the result callback.
Returns:
  handle that can be used to cancel the operation.

#### releaseEndpoint

    void releaseEndpoint()

Releases the acquired endpoint potentially making it available for re-use.

#### discardEndpoint

    void discardEndpoint()

Shuts down and discards the acquired endpoint.

#### isEndpointConnected

    boolean isEndpointConnected()

Determines of there the endpoint is connected 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).

Returns:
  `true` if the endpoint is connected, `false` otherwise.

#### connectEndpoint

    org.apache.hc.core5.concurrent.Cancellable connectEndpoint(HttpClientContext context,
                                                               org.apache.hc.core5.concurrent.FutureCallback<AsyncExecRuntime> callback)

Initiates operation to connect the local 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:
  `context` - the execution context.
  `callback` - the result callback.
Returns:
  handle that can be used to cancel the operation.

#### disconnectEndpoint

    void disconnectEndpoint()

Disconnects the local endpoint from the initial hop in the connection route.

#### upgradeTls

    void upgradeTls(HttpClientContext context)

Upgrades transport security of the active connection by using the TLS security protocol.

Parameters:
  `context` - the execution context.

#### upgradeTls

    default void upgradeTls(HttpClientContext context,
                            org.apache.hc.core5.concurrent.FutureCallback<AsyncExecRuntime> callback)

Upgrades transport security of the active connection by using the TLS security protocol.

Parameters:
  `context` - the execution context.
Since:
  5.2

#### getEndpointInfo

    default EndpointInfo getEndpointInfo()

Returns information about the underlying endpoint when connected or `null` otherwise.

#### validateConnection

    boolean validateConnection()

Validates the connection making sure it can be used to execute requests.

Returns:
  `true` if the connection is valid, `false`.

#### execute

    org.apache.hc.core5.concurrent.Cancellable execute(String id,
                                                       org.apache.hc.core5.http.nio.AsyncClientExchangeHandler exchangeHandler,
                                                       HttpClientContext context)

Initiates a message exchange using the given handler.

Parameters:
  `id` - unique operation ID or `null`.
  `exchangeHandler` - the client message handler.
  `context` - the execution context.

#### markConnectionReusable

    void markConnectionReusable(Object state,
                                org.apache.hc.core5.util.TimeValue validityTime)

Marks the connection as potentially re-usable for the given period of time and also marks it as stateful if the state representation is given.

Parameters:
  `state` - the connection state representation or `null` if stateless.
  `validityTime` - the period of time this connection is valid for.

#### markConnectionNonReusable

    void markConnectionNonReusable()

Marks the connection as non re-usable.

#### fork

    AsyncExecRuntime fork()

Forks this runtime for parallel execution.

Returns:
  another runtime with the same configuration.