Async Http Client

Asynchronous Http and WebSocket Client library for Java
Alternatives To Async Http Client
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Hoppscotch51,832117 hours ago1March 22, 2022152mitTypeScript
👽 Open source API development ecosystem -
Mitmproxy31,183423438 days ago53June 28, 2022281mitPython
An interactive TLS-capable intercepting HTTP proxy for penetration testers and software developers.
Curl30,3657316 hours ago30May 11, 202289otherC
A command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features
Echo25,7721,60610 days ago165September 04, 202266mitGo
High performance, minimalist Go web framework
Iris24,026320a day ago212September 21, 202283bsd-3-clauseGo
The fastest HTTP/2 Go Web Framework. New, modern and easy to learn. Fast development with Code you control. Unbeatable cost-performance ratio :rocket:
Uwebsockets15,458112 days ago14October 20, 201827apache-2.0C++
Simple, secure & standards compliant web server for the most demanding of applications
Http Proxy Middleware9,937359,5366,52817 days ago78April 22, 202294mitTypeScript
:zap: The one-liner node.js http-proxy middleware for connect, express, next.js and more
4 days ago29mitC++
WebRTC/RTSP/RTMP/HTTP/HLS/HTTP-FLV/WebSocket-FLV/HTTP-TS/HTTP-fMP4/WebSocket-TS/WebSocket-fMP4/GB28181/SRT server and client framework based on C++11
17 hours ago1February 27, 20185otherC
Embedded Web Server
Starlette8,325288411a day ago123June 28, 202239bsd-3-clausePython
The little ASGI framework that shines. 🌟
Alternatives To Async Http Client
Select To Compare

Alternative Project Comparisons

Async Http Client

Build Maven Central

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 of Netty. It's compiled with Java 11.


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



AHC doesn't use SEMVER, and won't.

  • MAJOR = huge refactoring
  • MINOR = new features and minor API changes, upgrading should require 1 hour of work to adapt sources
  • FIX = no API change, just bug fixes, only those are source and binary compatible with same minor version

Check for migration path between versions.


Feel free to check the Javadoc or the code for more information.


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

import static org.asynchttpclient.Dsl.*;


import static org.asynchttpclient.Dsl.*;

AsyncHttpClient asyncHttpClient=asyncHttpClient();

AsyncHttpClient instances must be closed (call the close 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 closing those shared resources.


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

import static org.asynchttpclient.Dsl.*;

AsyncHttpClient c=asyncHttpClient(config().setProxyServer(proxyServer("",38080)));


Sending Requests


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.

import org.asynchttpclient.*;

// bound
Future<Response> whenResponse=asyncHttpClient.prepareGet("").execute();

// unbound
        Request request=get("").build();
        Future<Response> whenResponse=asyncHttpClient.executeRequest(request);

Setting Request Body

Use the setBody method to add a body to the request.

This body can be of type:

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

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


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

This part can be of type:

  • ByteArrayPart
  • FilePart
  • InputStreamPart
  • StringPart

Dealing with Responses

Blocking on the Future

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

Future<Response> whenResponse=asyncHttpClient.prepareGet("").execute();
        Response response=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 to NOT BLOCK the calling thread!

Setting callbacks on the ListenableFuture

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

        ListenableFuture<Response> whenResponse = ???;
        Runnable callback = () - > {
            try {
               Response response = whenResponse.get();
            } catch (InterruptedException | ExecutionException e) {

        java.util.concurrent.Executor executor = ???;
        whenResponse.addListener(() - > ??? , executor);

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

Using custom AsyncHandlers

execute methods can take an org.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 a org.asynchttpclient.AsyncCompletionHandler;

AsyncHandler methods can let you abort processing early (return AsyncHandler.State.ABORT) and can let you return a computation result from onCompleted that will be used as the Future's result. See AsyncCompletionHandler implementation as an example.

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

Note that returning ABORT closes the underlying connection.

import static org.asynchttpclient.Dsl.*;

import org.asynchttpclient.*;
import io.netty.handler.codec.http.HttpHeaders;

Future<Integer> whenStatusCode = asyncHttpClient.prepareGet("")
        .execute(new AsyncHandler<Integer> () {
            private Integer status;
            public State onStatusReceived(HttpResponseStatus responseStatus) throws Exception {
                status = responseStatus.getStatusCode();
                return State.ABORT;
            public State onHeadersReceived(HttpHeaders headers) throws Exception {
              return State.ABORT;
            public State onBodyPartReceived(HttpResponseBodyPart bodyPart) throws Exception {
                 return State.ABORT;
            public Integer onCompleted() throws Exception{
                return status;
            public void onThrowable(Throwable t) {

        Integer statusCode = whenStatusCode.get();

Using Continuations

ListenableFuture has a toCompletableFuture method that returns a CompletableFuture. Beware that canceling this CompletableFuture won't properly cancel the ongoing request. There's a very good chance we'll return a CompletionStage instead in the next release.

CompletableFuture<Response> whenResponse=asyncHttpClient
        .exceptionally(t->{ /* Something wrong happened... */  })
        .thenApply(response->{ /*  Do something with the Response */ return resp;});
        whenResponse.join(); // wait for completion

You may get the complete maven project for this simple demo from org.asynchttpclient.example


Async Http Client also supports WebSocket. You need to pass a WebSocketUpgradeHandler where you would register a WebSocketListener.

WebSocket websocket=c.prepareGet("ws://")
        .execute(new WebSocketUpgradeHandler.Builder().addWebSocketListener(
        new WebSocketListener(){

            public void onOpen(WebSocket websocket){

            public void onClose(WebSocket websocket) {
                // ...

            public void onTextFrame(String payload,boolean finalFragment,int rsv){

            public void onError(Throwable t){


AsyncHttpClient has build in support for the WebDAV protocol. The API can be used the same way normal HTTP request are made:

        Request mkcolRequest=new RequestBuilder("MKCOL").setUrl("http://host:port/folder1").build();
        Response response=c.executeRequest(mkcolRequest).get();


        Request propFindRequest=new RequestBuilder("PROPFIND").setUrl("http://host:port").build();
        Response response=c.executeRequest(propFindRequest,new AsyncHandler() {
            // ...


You can find more information on Jean-Franois Arcand's blog. Jean-Franois is the original author of this library. Code is sometimes not up-to-date but gives a pretty good idea of advanced features.

User Group

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

GitHub Discussions


Of course, Pull Requests are welcome.

Here are the few rules we'd like you to respect if you do so:

  • Only edit the code related to the suggested change, so DON'T automatically format the classes you've edited.
  • Use IntelliJ default formatting rules.
  • Regarding licensing:
    • You must be the original author of the code you suggest.
    • You must give the copyright to "the AsyncHttpClient Project"
Popular Websocket Projects
Popular Http Projects
Popular Networking Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Http Client