Migration

Migrate from Vert.x 4 to 5

This guide describes the updates in Eclipse Vert.x 5 release. Use the information to upgrade your Vert.x 4.x applications to Vert.x 5. It provides information about the new, deprecated and unsupported features in this release.

Depending on the modules used in your application, you can read the relevant section to know more about the changes in Vert.x 5.

About Vert.x

Vert.x is a toolkit used for creating reactive, non-blocking, and asynchronous applications that run on Java Virtual Machine. (JVM). It contains several components that help you create reactive applications. It is designed to be cloud-native.

Since Vert.x supports asynchronous applications it can be used to create applications with high volume of messages, large event processing, HTTP interactions, and so on.

What’s changed in Vert.x 5

This section explains the fundamental differences between Vert.x 5 and 4.x releases.

`vertx` command-line tool removal

The vertx command-line tool has been removed in Vert.x 5.

We want to focus on the use case of the typical Vert.x application: compiled and optionally packaged as an executable uber-jar.

You can do this with Maven and the Vert.x Maven Plugin. The plugin can create a new Maven project in your repository or update an existing one.

In addition to packaging the application as an executable uber-jar, it can also start your application in development mode (redeploying the main verticle when file changes are detected).

If you’re a Gradle user, the Vert.x Gradle Plugin provides similar features.

CLI framework deprecation

The CLI framework is deprecated in Vert.x 5. This includes the io.vertx.core.Launcher class, which is based on it.

If your application is a command-line tool or needs one, checkout alternatives like Picocli. In fact, in various aspects, Picocli is more flexible and more powerful than the Vert.x CLI framework.

Vert.x Legacy CLI

If, while evaluating alternatives, you need to preserve the CLI framework functionality, you may do so by adding this dependency to your project (Maven):

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-launcher-legacy-cli</artifactId>
  <version>5.0.0</version>
</dependency>

This new project contains the legacy CLI framework, including the io.vertx.core.Launcher class.

Beware it is not guaranteed that backward compatibility can be maintained for the whole Vert.x 5 lifetime.

Vert.x Application Launcher

In Vert.x 5, a new module, the Vert.x Application Launcher replaces the Vert.x 4.x io.vertx.core.Launcher class.

First, you must add it to your project’s dependencies (Maven):

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-launcher-application</artifactId>
  <version>5.0.0</version>
</dependency>

To start your application, use io.vertx.launcher.application.VertxApplication as the main class.

# Assuming the command is executed on a Unix-like system which has the classpath configured in the CLASSPATH environment variable.
java -cp $CLASSPATH io.vertx.launcher.application.VertxApplication my.app.MainVerticle

If your application is packaged as an executable JAR, having the Main-Class attribute set to io.vertx.launcher.application.VertxApplication in the META-INF/MANIFEST.MF file, the command can be simplified.

java -jar myapp.jar my.app.MainVerticle

Handling deprecations and removals

Some features and functions have been deprecated or removed in Vert.x 5. Before you migrate your applications to Vert.x 5, check for deprecations and removals.

Some APIs were deprecated in an Vert.x 4.x release and new equivalent APIs were provided in that release.
The deprecated APIs have been removed in Vert.x 5.

If your application uses a deprecated API, you should update your application to use the new API. This helps in migrating applications to the latest version of the product.

The Java compiler generates warnings when deprecated APIs are used. You can use the compiler to check for deprecated methods while migrating applications to Vert.x 5.

Migrate from Vert.x 3 to 4