Repository files navigation

Follow@AsyncHttpClient on Twitter.

The AsyncHttpClient (AHC) library allows Java applications to easily execute HTTP requests and asynchronously process HTTP responses.The library also supports the WebSocket Protocol.

It's built on top ofNetty. It's compiled with Java 11.

Binaries are deployed on Maven Central.Add a dependency on the main AsyncHttpClient artifact:

Maven:

<dependencies>    <dependency>        <groupId>org.asynchttpclient</groupId>        <artifactId>async-http-client</artifactId>        <version>3.0.2</version>    </dependency></dependencies>

Gradle:

dependencies {    implementation'org.asynchttpclient:async-http-client:3.0.2'}

Import the Dsl helpers to use convenient methods to bootstrap components:

importstaticorg.asynchttpclient.Dsl.*;

importstaticorg.asynchttpclient.Dsl.*;AsyncHttpClientasyncHttpClient=asyncHttpClient();

AsyncHttpClient instances must be closed (call theclose method) once you're done with them, typically when shutting down your application.If you don't, you'll experience threads hanging and resource leaks.

AsyncHttpClient instances are intended to be global resources that share the same lifecycle as the application.Typically, AHC will usually underperform if you create a new client for each request, as it will create new threads and connection pools for each.It's possible to create shared resources (EventLoop and Timer) beforehand and pass them to multiple client instances in the config. You'll then be responsible for closingthose shared resources.

Finally, you can also configure the AsyncHttpClient instance via its AsyncHttpClientConfig object:

importstaticorg.asynchttpclient.Dsl.*;AsyncHttpClientc=asyncHttpClient(config().setProxyServer(proxyServer("127.0.0.1",38080)));

AHC provides 2 APIs for defining requests: bound and unbound.AsyncHttpClient and Dsl` provide methods for standard HTTP methods (POST, PUT, etc) but you can also pass a custom one.

importorg.asynchttpclient.*;// boundFuture<Response>whenResponse=asyncHttpClient.prepareGet("http://www.example.com/").execute();// unboundRequestrequest=get("http://www.example.com/").build();Future<Response>whenResponse=asyncHttpClient.executeRequest(request);

Use thesetBody method to add a body to the request.

This body can be of type:

• java.io.File
• byte[]
• List<byte[]>
• String
• java.nio.ByteBuffer
• java.io.InputStream
• Publisher<io.netty.buffer.ByteBuf>
• org.asynchttpclient.request.body.generator.BodyGenerator

BodyGenerator is a generic abstraction that let you create request bodies on the fly.Have a look atFeedableBodyGenerator if you're looking for a way to pass requests chunks on the fly.

Use theaddBodyPart method to add a multipart part to the request.

This part can be of type:

• ByteArrayPart
• FilePart
• InputStreamPart
• StringPart

execute methods return ajava.util.concurrent.Future. You can simply block the calling thread to get the response.

Future<Response>whenResponse=asyncHttpClient.prepareGet("http://www.example.com/").execute();Responseresponse=whenResponse.get();

This is useful for debugging but you'll most likely hurt performance or create bugs when running such code on production.The point of using a non blocking client is toNOT BLOCK the calling thread!

execute methods actually return aorg.asynchttpclient.ListenableFuture similar to Guava's.You can configure listeners to be notified of the Future's completion.

ListenableFuture<Response>whenResponse = ???;Runnablecallback = () - > {try {Responseresponse =whenResponse.get();System.out.println(response);            }catch (InterruptedException |ExecutionExceptione) {e.printStackTrace();            }        };java.util.concurrent.Executorexecutor = ???;whenResponse.addListener(() - > ??? ,executor);

If theexecutor parameter is null, callback will be executed in the IO thread.YouMUST NEVER PERFORM BLOCKING operations in there, typically sending another request and block on a future.

execute methods can take anorg.asynchttpclient.AsyncHandler to be notified on the different events, such as receiving the status, the headers and body chunks.When you don't specify one, AHC will use aorg.asynchttpclient.AsyncCompletionHandler;

AsyncHandler methods can let you abort processing early (returnAsyncHandler.State.ABORT) and can let you return a computation result fromonCompleted that will be usedas the Future's result.SeeAsyncCompletionHandler implementation as an example.

The below sample just capture the response status and skips processing the response body chunks.

Note that returningABORT closes the underlying connection.

importstaticorg.asynchttpclient.Dsl.*;importorg.asynchttpclient.*;importio.netty.handler.codec.http.HttpHeaders;Future<Integer>whenStatusCode =asyncHttpClient.prepareGet("http://www.example.com/")        .execute(newAsyncHandler<Integer> () {privateIntegerstatus;@OverridepublicStateonStatusReceived(HttpResponseStatusresponseStatus)throwsException {status =responseStatus.getStatusCode();returnState.ABORT;            }@OverridepublicStateonHeadersReceived(HttpHeadersheaders)throwsException {returnState.ABORT;            }@OverridepublicStateonBodyPartReceived(HttpResponseBodyPartbodyPart)throwsException {returnState.ABORT;            }@OverridepublicIntegeronCompleted()throwsException{returnstatus;            }@OverridepublicvoidonThrowable(Throwablet) {t.printStackTrace();            }        });IntegerstatusCode =whenStatusCode.get();

ListenableFuture has atoCompletableFuture method that returns aCompletableFuture.Beware that canceling thisCompletableFuture won't properly cancel the ongoing request.There's a very good chance we'll return aCompletionStage instead in the next release.

CompletableFuture<Response>whenResponse=asyncHttpClient        .prepareGet("http://www.example.com/")        .execute()        .toCompletableFuture()        .exceptionally(t->{/* Something wrong happened... */  })        .thenApply(response->{/*  Do something with the Response */returnresp;});whenResponse.join();// wait for completion

You may get the complete maven project for this simple demofromorg.asynchttpclient.example

Async Http Client also supports WebSocket.You need to pass aWebSocketUpgradeHandler where you would register aWebSocketListener.

WebSocketwebsocket =c.prepareGet("ws://demos.kaazing.com/echo")        .execute(newWebSocketUpgradeHandler.Builder().addWebSocketListener(newWebSocketListener() {@OverridepublicvoidonOpen(WebSocketwebsocket) {websocket.sendTextFrame("...").sendTextFrame("...");                  }@OverridepublicvoidonClose(WebSocketwebsocket) {// ...                  }@OverridepublicvoidonTextFrame(Stringpayload,booleanfinalFragment,intrsv) {System.out.println(payload);                  }@OverridepublicvoidonError(Throwablet) {t.printStackTrace();                  }                }).build()).get();

Keep up to date on the library development by joining the Asynchronous HTTP Client discussion group

GitHub Discussions