Vert.x

Vert.x contains a HTTP client that makes it easy to make HTTP requests asynchronously. Remember, every IO action in Vert.x must be performed asynchronously to avoid blocking the event loop. The event loop is the thread(s) that manages your verticles and their handlers. Java's built-in URL and URLConnection are not asynchronous, so you should not use these classes in your Vert.x apps.

Creating an HTTP Client

You create a Vert.x HTTP client like this:

HttpClient httpClient = vertx.createHttpClient();

When you create a Vert.x HTTP client from inside a verticle, it looks like this:

public class VertxHttpClientVerticle extends AbstractVerticle {

    @Override
    public void start() throws Exception {
        HttpClient httpClient = vertx.createHttpClient();
    }
}

Sending a GET Request

Once you have created the Vert.x HTTP client you can send a GET request using its getNow() method. Here is a Vert.x HttpClient getNow() example:

httpClient.getNow(80, "tutorials.jenkov.com", "/", new Handler<HttpClientResponse>() {

    @Override
    public void handle(HttpClientResponse httpClientResponse) {
        System.out.println("Response received");
    }
});

The first parameter to the getNow() method is the TCP port to connect to the remote HTTP server on. The getNow() method exists in a version where you can leave the port out. The port will then default to port 80 which is the HTTP protocol's default TCP port.

The second parameter to the getNow() method is the domain name of the remote HTTP server to connect to. Notice that there is not "http://" in front of the domain name. The Vert.x HTTP client knows that this is an HTTP request, so you don't need to include the protocol in the domain name.

The third parameter to the getNow() method is the URI to the resource to retrieve. The example above retrieves the frontpage of the website ("/"). Another URI could have been "/vert.x/index.html".

The fourth parameter is a Handler implementation which is called when the response for the HTTP request is received. How to handle the HTTP response is explained below.

Handling the HTTP Response

The Handler implementation passed to the getNow() method is called when the headers of the HTTP response are received. If you do not need to access the response body, you can process the response already in this handler.

However, if you do need to access the body of the HTTP response, you need to register another handler on the HttpClientResponse that is passed as parameter to the first Handler's handle() method. Here is how that looks:

httpClient.getNow(80, "tutorials.jenkov.com", "/", new Handler<HttpClientResponse>() {

    @Override
    public void handle(HttpClientResponse httpClientResponse) {

        httpClientResponse.bodyHandler(new Handler<Buffer>() {
            @Override
            public void handle(Buffer buffer) {
                System.out.println("Response (" + buffer.length() + "): ");
                System.out.println(buffer.getString(0, buffer.length()));
            }
        });
    }
});

The Handler implementation passed to the bodyHandler() method of the HttpClientResponse is called when the full HTTP response body is received.

The Buffer passed as parameter to the body Handler contains the full HTTP response.

More Methods

The HttpClient contains a lot more methods for sending GET, POST, PUT, DELETE and HEAD requests. It also contains more options for configuring the HttpClient with defaults, and for handling the HTTP response asynchronously, incrementally, as the response body is received (instead of when the full body is received). See the Vert.x JavaDoc for more info about these options.