Get started | Eclipse Vert.x (2024)

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

Before starting, you need:

JDK 1.8 or higher
A text editor or IDE
Maven 3 or higher
curl or HTTPie or a browser to perform HTTP requests

1 Bootstrap

To create a new project, go to start.vertx.io.

Choose the version of Vert.x you want to use, choose Java as the language, Maven as the build tool, andtype the group id and artifact id you want. Then, add Vert.x Web as a dependency by typing it in the “Dependencies” text box. When you’re done, hit the Generate Project button.Save the zip on your computer and unzip it in a folder of your choice.

The generated project contains:

The Maven build descriptor pom.xml configured to build and run your application
A sample Verticle and a sample test using JUnit 5
An editor configuration to enforce code style
A Git configuration to ignore files

If you want to try it now, you can download this sample project usingMaven or using Gradle.

2 Code

Open the project in the editor of your choice and navigate to src/main/java/com/example/starter/MainVerticle.java.This source file contains a sample Verticle (the Vert.x deployment unit) that starts an HTTP server.You’re going to modify it to greet whoever performs requests to your server.Change the code as follows:

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 creates a Vert.x Web Router (the object used to route HTTP requests to specific request handlers)and starts an HTTP Server on port 8888. On each request, it returns a JSON object containing the address of the request, the query parameter name, and a greeting message.

3 Run

To run the code, open a terminal and navigate to your project folder.Build the application as follows:

$ mvn package

Then, run the application:

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

Now that the server is up and running, try to send a request:

HTTPie

curl

$ http http://localhost:8888HTTP/1.1 200 OKcontent-length: 115content-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 OKcontent-length: 119content-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 pointers to help guide you further along your journey:

IntroRead our short introduction into reactive programming with Eclipse Vert.xDocumentationDeep dive through the documentation to check out all Vert.x modulesHow-tosCheck out the Vert.x How-tos to get pragmatic guides for specific topics