Get started with Vert.x

In this guide, you’ll learn how to get started with a new Vert.x Web project.

Be­fore start­ing, you need:

  • JDK 1.8 or higher
  • A text ed­i­tor or IDE
  • Maven 3 or higher
  • curl or HTTPie or a browser to per­form HTTP re­quests

1 Bootstrap

To cre­ate a new project, go to start.vertx.io.

Choose the ver­sion of Vert.x you want to use, choose Java as the lan­guage, Maven as the build tool, and type the group id and ar­ti­fact id you want. Then, add Vert.x Web as a de­pen­dency by typ­ing it in the “De­pen­den­cies” text box. When you’re done, hit the Gen­er­ate Project but­ton. Save the zip on your com­puter and unzip it in a folder of your choice.

The gen­er­ated project con­tains:

  • The Maven build de­scrip­tor pom.xml con­fig­ured to build and run your ap­pli­ca­tion
  • A sam­ple Ver­ti­cle and a sam­ple test using JUnit 5
  • An ed­i­tor con­fig­u­ra­tion to en­force code style
  • A Git con­fig­u­ra­tion to ig­nore files

If you want to try it now, you can down­load this sam­ple project using Maven or using Gra­dle

2 Code

Open the project in the ed­i­tor of your choice and nav­i­gate to src/main/java/com/example/starter/MainVerticle.java. This source file con­tains a sam­ple Verticle (the Vert.x de­ploy­ment unit) that starts an HTTP server. You’re going to mod­ify it to greet who­ever per­forms re­quests to your server. Change the code as fol­lows:

Java
Kotlin
Groovy
public class MainVerticle extends AbstractVerticle {
  @Override
  public void start() throws Exception {
    // Create a Router
    Router router = Router.router(vertx);

    // Mount the handler for all incoming requests at every path and HTTP method
    router.route().handler(context -> {
      // Get the address of the request
      String address = context.request().connection().remoteAddress().toString();
      // Get the query parameter "name"
      MultiMap queryParams = context.queryParams();
      String name = queryParams.contains("name") ? queryParams.get("name") : "unknown";
      // Write a json response
      context.json(
        new JsonObject()
          .put("name", name)
          .put("address", address)
          .put("message", "Hello " + name + " connected from " + address)
      );
    });

    // Create the HTTP server
    vertx.createHttpServer()
      // Handle every request using the router
      .requestHandler(router)
      // Start listening
      .listen(8888)
      // Print the port
      .onSuccess(server ->
        System.out.println(
          "HTTP server started on port " + server.actualPort()
        )
      );
  }
}
class MainVerticle : AbstractVerticle() {
  override fun start() {
    // Create a Router
    val router = Router.router(vertx)

    // Mount the handler for all incoming requests at every path and HTTP method
    router.route().handler { context ->
      // Get the address of the request
      val address = context.request().connection().remoteAddress().toString()
      // Get the query parameter "name"
      val queryParams = context.queryParams()
      val name = queryParams.get("name") ?: "unknown"
      // Write a json response
      context.json(
          json {
            obj(
              "name" to name,
              "address" to address,
              "message" to "Hello $name connected from $address"
            )
          }
      )
    }

    // Create the HTTP server
    vertx.createHttpServer()
        // Handle every request using the router
        .requestHandler(router)
        // Start listening
        .listen(8888)
        // Print the port
        .onSuccess { server ->
          println("HTTP server started on port " + server.actualPort())
        }
  }
}
class MainVerticle extends AbstractVerticle {
  @Override
  void start() {
    // Create a Router
    def router = Router.router(vertx)

    // Mount the handler for all incoming requests at every path and HTTP method
    router.route().handler { context ->
      // Get the address of the request
      def address = context.request().connection().remoteAddress().toString()
      // Get the query parameter "name"
      def queryParams = context.queryParams()
      String name = queryParams.get("name") ?: "unknown"
      // Write a json response
      context.json(
        new JsonObject()
          .put("name", name)
          .put("address", address)
          .put("message", "Hello " + name + " connected from " + address)
      )
    }

    // Create the HTTP server
    vertx.createHttpServer()
      // Handle every request using the router
      .requestHandler(router)
      // Start listening
      .listen(8888)
      // Print the port
      .onSuccess { server ->
        println("HTTP server started on port " + server.actualPort())
      }
  }
}

This code cre­ates a Vert.x Web Router (the ob­ject used to route HTTP re­quests to spe­cific re­quest han­dlers) and starts an HTTP Server on port 8888. On each re­quest, it re­turns a JSON ob­ject con­tain­ing the ad­dress of the re­quest, the query pa­ra­me­ter name, and a greet­ing mes­sage.

3 Run

To run the code, open a ter­mi­nal and nav­i­gate to your project folder. Build the ap­pli­ca­tion as fol­lows:

$ mvn package

Then, run the ap­pli­ca­tion:

$ mvn exec:java
HTTP server started on port 8888
apr 03, 2020 11:49:21 AM io.vertx.core.impl.launcher.commands.VertxIsolatedDeployer
INFO: Succeeded in deploying verticle

Now that the server is up and run­ning, try to send a re­quest:

HTTPie
curl
$ http http://localhost:8888
HTTP/1.1 200 OK
content-length: 115
content-type: application/json; charset=utf-8

{
    "address": "0:0:0:0:0:0:0:1:32806",
    "message": "Hello unknown connected from 0:0:0:0:0:0:0:1:32806",
    "name": "unknown"
}

$ http http://localhost:8888\?name\="Francesco"
HTTP/1.1 200 OK
content-length: 119
content-type: application/json; charset=utf-8

{
    "address": "0:0:0:0:0:0:0:1:32822",
    "message": "Hello Francesco connected from 0:0:0:0:0:0:0:1:32822",
    "name": "Francesco"
}
$ curl -v http://localhost:8888
*   Trying ::1:8888...
* Connected to localhost (::1) port 8888 (#0)
> GET / HTTP/1.1
> Host: localhost:8888
> User-Agent: curl/7.69.1
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< content-type: application/json; charset=utf-8
< content-length: 115
<
* Connection #0 to host localhost left intact
{"name":"unknown","address":"0:0:0:0:0:0:0:1:59610","message":"Hello unknown connected from 0:0:0:0:0:0:0:1:59610"}

$ curl -v http://localhost:8888\?name\="Francesco"
*   Trying ::1:8888...
* Connected to localhost (::1) port 8888 (#0)
> GET /?name=Francesco HTTP/1.1
> Host: localhost:8888
> User-Agent: curl/7.69.1
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< content-type: application/json; charset=utf-8
< content-length: 119
<
* Connection #0 to host localhost left intact
{"name":"Francesco","address":"0:0:0:0:0:0:0:1:59708","message":"Hello Francesco connected from 0:0:0:0:0:0:0:1:59708"}

4 Go further

Now that you have had a taste of how easy and fun it is to get started with Vert.x, here are a few point­ers to help guide you fur­ther along your jour­ney: