Tech and Media Labs
This site uses cookies to improve the user experience.




Vert.x HTTP Server

Jakob Jenkov
Last update: 2015-11-13

Vert.x makes it easy to create an HTTP server so your application can receive HTTP requests. You can create one or more HTTP servers, depending on your need. In this tutorial I will look at how to create an HTTP server from inside a verticle and how to handle requests.

Creating an HTTP Server

Creating an HTTP server is done using the Vertx instance method createHttpServer(). Here is an example of creating an HTTP server in Vert.x:

 HttpServer httpServer = vertx.createHttpServer();

It is common to start an HTTP server from within an verticle. That way all handlers registered on the HTTP server will be executed by the same thread that started the verticle.

import io.vertx.core.AbstractVerticle;
import io.vertx.core.http.HttpServer;

public class VertxHttpServerVerticle extends AbstractVerticle {

    private HttpServer httpServer = null;

    @Override
    public void start() throws Exception {
        httpServer = vertx.createHttpServer();

    }
}

Starting the HTTP Server

Once you have created the HTTP server, you can start it using its listen() method. Here is how starting the HTTP server looks:

public class VertxHttpServerVerticle extends AbstractVerticle {

    private HttpServer httpServer = null;

    @Override
    public void start() throws Exception {
        httpServer = vertx.createHttpServer();

        httpServer.listen(9999);
    }
}

The HttpServer class has more versions of the listen() method too, which gives you different options for starting the HTTP server.

Setting a Request Handler on the HTTP Server

In order to handle incoming HTTP requests you must set a request handler on the HTTP server. This is normally done before starting the server. Here is a Vert.x HTTP server request handler example:

public class VertxHttpServerVerticle extends AbstractVerticle {

    private HttpServer httpServer = null;

    @Override
    public void start() throws Exception {
        httpServer = vertx.createHttpServer();

        httpServer.requestHandler(new Handler<HttpServerRequest>() {
            @Override
            public void handle(HttpServerRequest request) {
                System.out.println("incoming request!");
            }
        });

        httpServer.listen(9999);
    }
}

Every time an HTTP request arrives at the HTTP server, the handle() method of the Handler object is called. Inside the handle() method you can execute the code needed to handle the HTTP request.

Request Headers and Parameters

You can access HTTP headers and parameters from the HttpServerRequest object passed as parameter to the handle() method. Here is an example showing how to access a few of the properties of a HTTP request:

httpServer.requestHandler(new Handler<HttpServerRequest>() {
    @Override
    public void handle(HttpServerRequest request) {
        System.out.println("incoming request!");

        request.uri();
        request.path();
        request.getParam("p1");
    }
});

Handling POST Requests

If the HTTP request is a HTTP POST request you need to handle it a bit differently. You need to attach a body handler to the HTTP request. The body handler is called whenever data from the request body arrives. Here is how that looks:

httpServer.requestHandler(new Handler<HttpServerRequest>() {
    @Override
    public void handle(HttpServerRequest request) {
        System.out.println("incoming request!");

        if(request.method() == HttpMethod.POST){
            request.handler(new Handler<Buffer>() {
                @Override
                public void handle(Buffer buffer) {
                        
                }
            });
        }
    }
});

If you want to wait until the full HTTP POST body has arrived you can attach an end handler instead. The end handler is not called until the full HTTP POST body has been received. However, the end handler does not have direct access to the full HTTP POST body. You need to collect that in the request handler. Here is a Vert.x HTTP request end handler example which does all that:


httpServer.requestHandler(new Handler<HttpServerRequest>() {

    @Override
    public void handle(HttpServerRequest request) {
        System.out.println("incoming request!");

        Buffer fullRequestBody = Buffer.buffer();
        if(request.method() == HttpMethod.POST){

            request.handler(new Handler<Buffer>() {
                @Override
                public void handle(Buffer buffer) {
                    fullRequestBody.appendBuffer(buffer);
                }
            }

            request.endHandler(new Handler<Buffer>() {
                @Override
                public void handle(Buffer buffer) {
                    // here you can access the 
                    // fullRequestBody Buffer instance.
                }
            });
        }
    }
});

Sending Back an HTTP Response

You can of course send back an HTTP response for an incoming HTTP request. To do so you need to obtain the HttpServerResponse instance from the request object. This is how you obtain the HttpServerResponse object:

HttpServerResponse response = request.response();

Once you have obtained a HttpServerResponse instance you can set the HTTP response status code and headers like this:

response.setStatusCode(200);
response.headers()
    .add("Content-Length", String.valueOf(57))
    .add("Content-Type", "text/html")
;

After writing the headers back you can write the response body back via the write() method, like this:

response.write("Vert.x is alive!");
response.end();

You can call write() multiple times to add more data to the response body. The write() method also exists in a version that takes a Vert.x Buffer instance as parameter. This method will write the contents of the Buffer to the HTTP response.

The write() method is asynchronous and returns immediately after queuing up the string or buffer.

Once you have finished writing the HTTP response body you should end the HTTP response. This is done by calling the end() method as shown in the previous example. You can also write the HTTP response body and end the response in a single method call, like this:

response.end("Vert.x is alive!");

The end() method can take either a String or Buffer as parameter. The parameter will be written to the response body, and the response ended after that.

Closing the HTTP Server

To close an HTTP server you simply call its close() method like this:

httpServer.close();

The close() method executes asynchronously, so the HTTP server may not be fully closed by the time the close() method returns. You can pass a close handler as parameter to the close() method, to be notified when the HTTP server is fully closed.

Jakob Jenkov




Copyright  Jenkov Aps
Close TOC