Package org.jboss.resteasy.client.jaxrs.engines

## Class ApacheHttpAsyncClient4Engine

- java.lang.Object
- - org.jboss.resteasy.client.jaxrs.engines.ApacheHttpAsyncClient4Engine

- All Implemented Interfaces:
    `Closeable`, `AutoCloseable`, `ClientHttpEngine`, `AsyncClientHttpEngine`

      public class ApacheHttpAsyncClient4Engine
      extends Object
      implements AsyncClientHttpEngine, Closeable

  AsyncClientHttpEngine using apache http components HttpAsyncClient 4.

  Some words of caution:

  - Asynchronous IO means non-blocking IO utilizing few threads, typically at most as much threads as number of cores. As such, performance may profit from fewer thread switches and less memory usage due to fewer thread-stacks. But doing synchronous, blocking IO (the invoke-methods not returning a future) may suffer, because the data has to be transferred piecewiese to/from the io-threads.
  - Request-Entities are fully buffered in memory, thus this engine is unsuitable for very large uploads.
  - Response-Entities are buffered in memory, except if requesting a Response, InputStream or Reader as Result. Thus for large downloads or COMET one of these three return types must be requested, but there may be a performance penalty because the response-body is transferred piecewise from the io-threads. When using InvocationCallbacks, the response is always fully buffered in memory.
  - InvocationCallbacks are called from within the io-threads and thus must not block or else the application may slow down to a halt. Reading the response is safe (because the response is buffered in memory), as are other async (and in-memory) Client-invocations (the submit-calls returning a future not containing Response, InputStream or Reader). Again, there must be no blocking IO inside InvocationCallback! (If you are wondering why not to allow blocking calls by wrapping InvocationCallbacks in extra threads: Because then the main advantage of async IO, less threading, is lost.)
  - InvocationCallbacks may be called seemingly "after" the future-object returns. Thus, responses should be handled solely in the InvocationCallback.
  - InvocationCallbacks will see the same result as the future-object and vice versa. Thus, if the invocationcallback throws an exception, the future-object will not see it. Another reason to handle responses only in the InvocationCallback.
  Author:
    Markus Kull

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.jboss.resteasy.client.jaxrs.engines.AsyncClientHttpEngine

      `AsyncClientHttpEngine.ResultExtractor<T>`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected org.apache.http.impl.nio.client.CloseableHttpAsyncClient` | `client` |
    `protected boolean` | `closeHttpClient` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ApacheHttpAsyncClient4Engine​(org.apache.http.impl.nio.client.CloseableHttpAsyncClient client, boolean closeHttpClient)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` |
    `HostnameVerifier` | `getHostnameVerifier()` | Needed for Client.getHostnameVerifier()
    `SSLContext` | `getSslContext()` | Needed for Client.getSslContext();
    `javax.ws.rs.core.Response` | `invoke​(javax.ws.rs.client.Invocation request)` |
    `<T> Future<T>` | `submit​(ClientInvocation request, boolean buffered, javax.ws.rs.client.InvocationCallback<T> callback, AsyncClientHttpEngine.ResultExtractor<T> extractor)` | Submits an asynchronous request.
    `<T> CompletableFuture<T>` | `submit​(ClientInvocation request, boolean buffered, AsyncClientHttpEngine.ResultExtractor<T> extractor, ExecutorService executorService)` | Submits an asynchronous request.

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

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

    - ### Methods inherited from interface org.jboss.resteasy.client.jaxrs.engines.AsyncClientHttpEngine

      `submit`

    - ### Methods inherited from interface org.jboss.resteasy.client.jaxrs.ClientHttpEngine

      `isFollowRedirects, setFollowRedirects`

- - ### Field Detail

    - #### client

          protected final org.apache.http.impl.nio.client.CloseableHttpAsyncClient client

    - #### closeHttpClient

          protected final boolean closeHttpClient

  - ### Constructor Detail

    - #### ApacheHttpAsyncClient4Engine

          public ApacheHttpAsyncClient4Engine​(org.apache.http.impl.nio.client.CloseableHttpAsyncClient client,
                                              boolean closeHttpClient)

  - ### Method Detail

    - #### close

          public void close()

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

    - #### getSslContext

          public SSLContext getSslContext()

      Description copied from interface: `ClientHttpEngine`
      Needed for Client.getSslContext();
      Specified by:
        `getSslContext` in interface `ClientHttpEngine`
      Returns:
        `SSLContext`

    - #### getHostnameVerifier

          public HostnameVerifier getHostnameVerifier()

      Description copied from interface: `ClientHttpEngine`
      Needed for Client.getHostnameVerifier()
      Specified by:
        `getHostnameVerifier` in interface `ClientHttpEngine`
      Returns:
        `HostnameVerifier`

    - #### invoke

          public javax.ws.rs.core.Response invoke​(javax.ws.rs.client.Invocation request)

      Specified by:
        `invoke` in interface `ClientHttpEngine`

    - #### submit

          public <T> Future<T> submit​(ClientInvocation request,
                                      boolean buffered,
                                      javax.ws.rs.client.InvocationCallback<T> callback,
                                      AsyncClientHttpEngine.ResultExtractor<T> extractor)

      Description copied from interface: `AsyncClientHttpEngine`
      Submits an asynchronous request.
      Specified by:
        `submit` in interface `AsyncClientHttpEngine`
      Type Parameters:
        `T` - type
      Parameters:
        `request` - Request
        `buffered` - buffer the response?
        `callback` - Optional callback receiving the result, which is run inside the io-thread. may be null.
        `extractor` - ResultExtractor for extracting a result out of a ClientResponse. Is run inside the io-thread
      Returns:
        Future with the result or Exception

    - #### submit

          public <T> CompletableFuture<T> submit​(ClientInvocation request,
                                                 boolean buffered,
                                                 AsyncClientHttpEngine.ResultExtractor<T> extractor,
                                                 ExecutorService executorService)

      Description copied from interface: `AsyncClientHttpEngine`
      Submits an asynchronous request.
      Specified by:
        `submit` in interface `AsyncClientHttpEngine`
      Type Parameters:
        `T` - type
      Parameters:
        `request` - Request
        `buffered` - buffer the response?
        `extractor` - ResultExtractor for extracting a result out of a ClientResponse. Is run inside the io-thread
        `executorService` - the executor to use for asynchronous execution
      Returns:
        `CompletableFuture` with the result or Exception