Chapter 3. Features

From Eclipse Vert.x 4.3.4 onward, because of the upgrade to Micrometer 1.9.3, object names now include the metric type when using Eclipse Vert.x Micrometer Metrics with Java Management Extensions (JMX).

This enhancement is only relevant for users of the micrometer-registry-jmx module.

From Eclipse Vert.x 4.3.3 onward, Eclipse Vert.x supports version 19 of GraphQL Java, which is the Java server implementation of the GraphQL query language. When using GraphQL Java 19, if you do not set a locale in the JVM, the GraphQL engine now uses the JVM default locale, which is the locale of the platform where the JVM is installed. Alternatively, you can configure the JVM default Locale to use a different value or you can use the Eclipse Vert.x Web GraphQL handler to set a custom locale.

From Eclipse Vert.x 4.3.2 onward, if you use the Jackson Databind library with the vertx-web-openapi, vertx-auth-webauthn, or vertx-config-yaml module, you must add the following dependency to the project descriptor:

<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
</dependency>

Because the Jackson Databind library has caused some security vulnerabilities and other modules typically only use Jackson Databind to perform some internal action, the use of Eclipse Vert.x parsers supersedes any need to use the vertx-web-openapi, vertx-auth-webauthn, or vertx-config-yaml module with Jackson Databind. However, if you want to continue using any of these modules with Jackson Databind, you must explicitly include this dependency in your project, as shown in the preceding example.

From Eclipse Vert.x 4.3.1 onward, Eclipse Vert.x OpenAPI requires use of the routerBuilder.rootHandler() method, to ensure that the body handler is set up in the correct order after any PLATFORM or SECURITY_POLICY handlers.

For example:

BodyHandler bodyHandler = BodyHandler.create("my-uploads");
routerBuilder.rootHandler(bodyHandler);

In earlier releases of Eclipse Vert.x, Eclipse Vert.x OpenAPI supported the routerBuild.bodyHandler() method for adding the body handler. However, the bodyHandler() method had the following disadvantages:

The bodyHandler() method is deprecated in Eclipse Vert.x 4.3.1. The preceding rootHandler call now supersedes the following bodyHandler call that was available in previous versions:

BodyHandler bodyHandler = BodyHandler.create("my-uploads");
routerBuilder.bodyHandler(bodyHandler);

From Eclipse Vert.x 4.3.1 onward, the Eclipse Vert.x reactive Oracle client includes the following enhancements for BLOB and RAW data:

From Eclipse Vert.x 4.3.1 onward, in the Eclipse Vert.x Oracle reactive client, the retrieval of automatically generated keys is disabled by default. The Eclipse Vert.x Oracle reactive client does not typically need to retrieve automatically generated keys, because most applications do not rely on the ROWID.

This enhancement also facilitates queries such as INSERT…​SELECT, which cannot run successfully when the retrieval of automatically generated keys is enabled.

From Eclipse Vert.x 4.3.0 onward, Eclipse Vert.x supports the io.vertx.core.shareddata.ClusterSerializable interface for reading and writing objects to and from a buffer, when these objects are either read from an AsyncMap or decoded from an EventBus message body.

Earlier releases of Eclipse Vert.x supported the io.vertx.core.shareddata.impl.ClusterSerializable interface. However, because this interface was provided in an implementation package, it was considered potentially less reliable. The io.vertx.core.shareddata.impl.ClusterSerializable interface is now deprecated in Eclipse Vert.x 4.3.0 and made public.

From Eclipse Vert.x 4.3.0 onward, in the MicrometerMetricsOptions class, the requestsTagsProvider option for server request metrics is renamed serverRequestTagsProvider. This enhancement is required because a similar clientRequestTagsProvider option is also now available for client request metrics.

In earlier releases of Eclipse Vert.x, the requestsTagsProvider option used a getter and a setter, which were named getRequestsTagsProvider and setRequestsTagsProvider, respectively. In Eclipse Vert.x 4.3.0 and later versions, the getter and setter for the serverRequestTagsProvider option are renamed getServerRequestTagsProvider and setServerRequestTagsProvider.

From Eclipse Vert.x 4.3.0 onward, when OAuth2 authorization is configured in on-behalf-of (OBO) mode, OAuth2 requires that an OAuth2Credentials object is explicitly specified to authorize requests.

For example:

oauth2.authenticate(
  new Oauth2Credentials().setAssertion("head.body.signature").addScope("a").addScope("b"))

In earlier releases of Eclipse Vert.x, OAuth2 authorization in OBO mode allowed the use of TokenCredentials. However, because the flow is optional, to allow reuse of the same OAuth2Credentials object, the preceding Oauth2Credentials call now supersedes the following type of TokenCredentials call that was available in previous versions:

oauth2.authenticate(
  new TokenCredentials("head.body.signature").addScope("a").addScope("b"));

From Eclipse Vert.x 4.3.0 onward, the RoutingContext.fileUploads() method returns a List<FileUpload> value. Storing file uploads in a list helps to preserve the order of the uploads.

For example:

List<FileUpload> uploads = ctx.fileUploads();

In earlier releases of Eclipse Vert.x, the RoutingContext.fileUploads() method returned a Set<FileUpload> value. However, storing file uploads in a set was not consistent with the World Wide Web Consortium (W3C) specification for form content types, because it did not preserve the correct order and users could not rely on the upload name to be a unique key. The preceding example now supersedes the following method declaration that was available in previous versions:

Set<FileUpload> uploads = ctx.fileUploads();

From Eclipse Vert.x 4.3.0 onward, the Route.subRouter(Router) method is the only supported way to implement a sub router.

Earlier releases of Eclipse Vert.x supported two different methods for implementing sub routers:

However, the behavior between these two methods was inconsistent, because the Router.mountSubRouter method allowed any path whereas the Route.subRouter method explicitly requires a wildcard asterisk (*) to represent the sub routing path. The Router.mountSubRouter method also delegated to the Route.subRouter method by appending the missing wildcard.

In Eclipse Vert.x 4.3.0 and later versions, the Router.mountSubRouter method is deprecated. Router objects must now also use the Route.subRouter method to implement sub routers. For example:

router.route("/eventbus/*").subRouter(otherRouter);

The preceding router.route().subRouter() call now supersedes the following type of router.mountSubRouter() call that was available in previous versions:

router.mountSubRouter("/eventbus", otherRouter);

From Eclipse Vert.x 4.3.0 onward, after a body handler parses the body of a web request, the body handler provides the body buffer to the routing context for the request. Caching the body buffer in the routing context means that multiple different handlers that want a decoded view of the request body can get the cached result without having to parse the body again. This enhancement also supports situations where the body content is of type application/json.

The RoutingContext class provides a new body() method that is used to get the request body as a specified type.

For example:

RoutingContext.body().asString()
RoutingContext.body().asString(String encoding)
RoutingContext.body().asJsonObject()
RoutingContext.body().asJsonArray()
RoutingContext.body().asJsonObject(int maxLength)
RoutingContext.body().asJsonArray(int maxLength)
RoutingContext.body().buffer()

The new body() getter also provides the following additional functionality:

// the length of the buffer (-1) for null buffers
RoutingContext.body().length()

// Converting to POJO
RoutingContext.body().asPOJO(Class<T> clazz)
RoutingContext.body().asPOJO(Class<T> clazz, int maxLength)

This enhancement provides the following advantages:

In earlier releases of Eclipse Vert.x, the RoutingContext class provided the following methods that are now deprecated in favor of using the body() method:

RoutingContext.getBodyAsString()
RoutingContext.getBodyAsString(String encoding)
RoutingContext.getBodyAsJson()
RoutingContext.getBodyAsJsonArray()
RoutingContext.getBodyAsJson(int maxLength)
RoutingContext.getBodyAsJsonArray(int maxLength)
RoutingContext.getBody()

From Eclipse Vert.x 4.3.0 onward, to avoid unnecessary traffic, notifications about changes in the Eclipse Vert.x circuit breaker state are disabled by default. To enable these notifications, call the setNotificationAddress method of the CircuitBreakerOptions object with a parameter that is not null.

For example:

CircuitBreakerOptions options = new CircuitBreakerOptions()
    .setNotificationAddress(CircuitBreakerOptions.DEFAULT_NOTIFICATION_ADDRESS);

When you enable notifications as shown in the preceding example, the default behavior is to send notifications to local consumers only. To send notifications on a cluster-wide basis, call the setNotificationLocalOnly method with a parameter of false.

For example:

CircuitBreakerOptions options = new CircuitBreakerOptions()
    .setNotificationAddress(CircuitBreakerOptions.DEFAULT_NOTIFICATION_ADDRESS)
    .setNotificationLocalOnly(false);

From Eclipse Vert.x 4.3.0 onward, the Eclipse Vert.x reactive SQL client supports pipelined queries and runs batch queries in pipelining mode by default. Pipelining means that requests are sent on the same connection without waiting for responses to previous requests.

In earlier releases of Eclipse Vert.x, because MySQL does not have native protocol support for batching, the SQL client ran batch queries by running prepared queries in a sequence, which the user could operate directly through API calls.

From Eclipse Vert.x 4.3.0 onward, Eclipse Vert.x includes the following MongoDB enhancements for hints and hint strings:

From Eclipse Vert.x 4.3.0 onward, when building a schema, use the JSON representation that the Eclipse Vert.x JSON schema provides. The JSON representation allows use of any validator.

For example:

JsonSchema schema = JsonSchema.of(dsl.toJson());

In earlier releases of Eclipse Vert.x, the SchemaBuilder class provided a build() method, which required use of a specific implementation of a validator. The build() method is deprecated in Eclipse Vert.x 4.3.0. The preceding JsonSchema example now supersedes the following type of build() method call that was available in previous versions:

Schema schema = dsl.build(parser);

From Eclipse Vert.x 4.2.7 onward, Eclipse Vert.x is certified for use with Red Hat OpenJDK 17.

From Eclipse Vert.x 4.2.4 onward, the RequestOptions method validates HTTP headers, and the request fails if a header name is invalid.

In earlier releases of Eclipse Vert.x, the HTTPClientRequest validated HTTP headers, because the RequestOptions method used a Multimap implementation that did not validate header names.

From Eclipse Vert.x 4.2.4 onward, the simple locale is used as the default locale for MongoDB collation.

Eclipse Vert.x 4.2.3 introduced support for the collation options to support language-specific rules for comparing strings. In Eclipse Vert.x 4.2.3, the platform default was used as the default locale. However, because the platform default is not a constant value, it could lead to failures on systems that use a locale that is not supported by MongoDB. For example, Locale.FR would work successfully, but Locale.FR_FR would not be supported

From Eclipse Vert.x 4.2.4 onward, the StaticHandler configuration properties for the webroot directory and file system access are defined in the StaticHandler factory constructor call.

For example, the following constructor call defines a webroot directory, static/resources, and relative file system access:

StaticHandler.create(FileSystemAccess.RELATIVE, "static/resources");

For example, the following constructor call defines a webroot directory, /home/paulo/Public, and root file system access:

StaticHandler.create(FileSystemAccess.ROOT, "/home/paulo/Public");

In earlier releases of Eclipse Vert.x, the allowRootFileSystemAccess and webroot properties were defined by using setters. However, these property values were not final, which could lead to invalid static configuration. In Eclipse Vert.x 4.2.4, the preceding constructor call now supersedes the following setter declarations:

StaticHandler.create()
  .setAllowRootFileSystemAccess(true)
  .setWebRoot("/home/paulo/Public");

From Eclipse Vert.x 4.2.0 onward, two distinct HTTP servers that are bound with a negative port number, such as -1, share the same random port within the instances of a specific verticle deployment. This means that multiple HTTP servers bound with port -1 will share the same random port. Similarly, multiple HTTP servers bound with port -2 will share the same random port, and so on. This port sharing behavior that is based on negative port numbers is independent of the verticle, because it allows different HTTP servers to have a different random port.

In earlier releases of Eclipse Vert.x, random server port sharing was based on two HTTP servers bound with port 0. However, this prevented the same verticle from binding two HTTP servers with different random ports within the instances of the same verticle.

Eclipse Vert.x 4.2.0 includes a new method, Set<Cookie> cookies(), that enables getting all cookies.

In earlier releases of Vert.x, the HttpServerRequest and HttpServerResponse interfaces used the following method that is now deprecated in Eclipse Vert.x 4.2.0:

Map<String, Cookie> cookieMap()

The RFC 6265 - HTTP State Management Mechanism specification states that each cookie is uniquely identified based on the tuple <name, domain, path>. However, the Map<String, Cookie> cookieMap() method used in earlier releases of Eclipse Vert.x wrongly assumed that cookies could be identified based on their name only. This meant that when multiple cookies shared the same name, the map held the last cookie to be parsed, and any previously parsed value was silently overwritten.

Eclipse Vert.x 4.2.0 supports version 17 of GraphQL Java, which is the Java server implementation of the GraphQL query language. With GraphQL Java 17, the GraphQLContext object is now the standard for sharing contextual data between components of a GraphQL Java application.

Eclipse Vert.x 4.2.0 introduces the following new mechanism to configure GraphQL execution:

GraphQLHandler handler = GraphQLHandler.create(graphQL).beforeExecute(builderWithContext -> {
  DataLoader<String, Link> linkDataLoader = DataLoaderFactory.newDataLoader(linksBatchLoader);
  DataLoaderRegistry dataLoaderRegistry = new DataLoaderRegistry().register("link", linkDataLoader);
  builderWithContext.builder().dataLoaderRegistry(dataLoaderRegistry);
});

In earlier releases of Eclipse Vert.x, the following hooks were used in Vert.x Web GraphQL handlers to configure a data loader. The following hooks are now deprecated in Eclipse Vert.x 4.2.0.

GraphQLHandler handler = GraphQLHandler.create(graphQL).dataLoaderRegistry(rc -> {
  DataLoader<String, Link> linkDataLoader = DataLoader.newDataLoader(linksBatchLoader);
  return new DataLoaderRegistry().register("link", linkDataLoader);
});

OpenJ9 images for IBM Z and IBM Power Systems have been deprecated. The following OpenJDK11 image has been updated to support multiple architectures:

You can use the OpenJDK11 image with the following architectures:

Red Hat build of Eclipse Vert.x runs on a FIPS enabled RHEL system and uses FIPS certified libraries provided by RHEL.

From Eclipse Vert.x 4.1.0 onward, if there are headers in an HTTP redirect, then the HTTP client redirect handler propagates the headers to the next request. This change enables the redirect handler to have more control over the entire redirected request.

In earlier releases of Eclipse Vert.x, where there were redirected requests with headers, the HTTP client would handle the headers after the redirect.

The following example shows you how redirects are handled in Eclipse Vert.x 4.1.0:

RequestOptions options = new RequestOptions();
options.setMethod(HttpMethod.GET);
options.setHost(uri.getHost());
options.setPort(port);
options.setSsl(ssl);
options.setURI(requestURI);

// From 4.1.0 propagate headers
options.setHeaders(resp.request().headers());
options.removeHeader(CONTENT_LENGTH);

In Eclipse Vert.x 4.1.0, the Infinispan cluster manager has been updated and is based on Infinispan 12.

Infinispan 11 had a bug, which did not allow storing of byte arrays in a multimap cache. As a wordaround, the Eclipse Vert.x cluster manager had to use an internal Infinispan class, WrappedBytes, to store eventbus subscription data. This issue has been fixed in Infinispan 12.

In Eclipse Vert.x 4.1.0, the JSON configuration options are applied even if a connection_string option is available.

The following configuration options are now applied:

{
    mongo:{
        db_name: "mydb"
        connection_string: "mongodb://localhost:27017"
        maxPoolSize: 10
        minPoolSize: 3
    }
}

In earlier releases of Eclipse Vert.x, the JSON configuration options were ignored when connection string was available. For example, consider the previous example. In earlier releases of Eclipse Vert.x, db_name, maxPoolSize, and minPoolSize options would have been ignored.

From Eclipse Vert.x 4.0 onward, the JWT and OAuth2 handlers are used to handle scopes.

From Eclipse Vert.x 4.1.0 onward, JWTOptions.setScopes(List<String>), JWTOptions.addScope(String) and JWTOptions.withScopeDelimiter(String) methods have been removed. These methods did not comply with the specification.

The following example shows you how to handle scopes in Eclipse Vert.x 4.1.0.

// before 4.1.0
JWTAuthOptions authConfig = new JWTAuthOptions()
  .setJWTOptions(new JWTOptions()
    .addScope("a")
    .addScope("b")
    .withScopeDelimiter(" ")));

JWTAuth authProvider = JWTAuth.create(vertx, authConfig);

router.route("/protected/*").handler(JWTAuthHandler.create(authProvider));

// in 4.1.0
JWTAuth authProvider = JWTAuth.create(vertx, new JWTAuthOptions());

router.route("/protected/*").handler(
  JWTAuthHandler.create(authProvider)
    .addScope("a")
    .addScope("b")
    .withScopeDelimiter(" "));

From Eclipse Vert.x 4.1.0, LoggerHandler.customFormatter(Function) method has been deprecated. The function takes as input an HttpServerRequest and returns a formatted log string. Because the output is a string, it is not possible to access the context.

Use the new method LoggerHandler customFormatter(LoggerFormatter formatter) instead. The method takes as input a custom formatter that gives access to the context.

From Eclipse Vert.x 4.1.0, a new exception class io.vertx.ext.web.handler.HttpException is available that can be used to handle HTTP failures. You can use the exception to specify custom status codes other than 500. For example, new HttpException(401, “Forbidden”) indicates that the requests that are forbidden should return status code 401.

From Eclipse Vert.x 4.1.0, RxJava 3 is supported.

From Eclipse Vert.x 4.0.3, the ContextServerInterceptor.bind() method binds all types of data to the context. The method is more secure now as it does not expose the storage details.

In releases prior to Eclipse Vert.x 4.0.3, the method used to bind only 'String' data type to context. It also exposed the storage details.

To use the updated ContextServerInterceptor.bind() method, you must update your application.

The following example shows the code in releases prior to Eclipse Vert.x 4.0.3.

// Example code from previous releases

class X extends ContextServerInterceptor {
  @Override
  public void bind(Metadata metadata, ConcurrentMap<String, String> context) {

The following example shows the replacing code fpr Eclipse Vert.x 4.0.3 release.

// Replacing code for Eclipse Vert.x 4.0.3 release

class X extends ContextServerInterceptor {
  @Override
  public void bind(Metadata metadata) {

In releases prior to Eclipse Vert.x 4.0.3, if routes were defined with a path ending in slash and a wildcard /*, the routes would be called only if the matching request also included the ending slash /. This rule caused problems when the wildcard was empty.

From Eclipse Vert.x 4.0.3 onward, this rule is no longer applied. You can create routes whose paths end in a slash (/). However, it is not mandatory to specify the slash in the request URLs.

Also, you can create and use request URLs to call routes that end with wildcards in their path instead of slash (/). For example, routes with wildcard can be defined as /foo/*. Here the route has to match an open wildcard at the end of the path. The request URL can be /foo.

The table shows the behavior in Eclipse Vert.x 4.0.3 and previous releases when you send a request URL /foo/*. You can see that the ending slash is optional in Eclipse Vert.x 4.0.3 and request matches the route.

The autoRegistrationOfImporters attribute has been removed from service discovery options.

In releases prior to Eclipse Vert.x 4.0.3, the AuthenticationProvider.authenticate() method would incorrectly take jwt: someValue as input credentials.

From Eclipse Vert.x 4.0.3, the AuthenticationProvider.authenticate() method has been updated and takes token: someValue as input credentials. This change ensures that both JSON and typed APIs are consistent and can be used interchangeably.

The following code shows the implementation for the authenticate method in releases prior to Eclipse Vert.x 4.0.3.

new JsonObject().put("jwt", "token...");

The following code shows the implementation for the authenticate method in Eclipse Vert.x 4.0.3 release.

new JsonObject().put("token", "token...");

The PubSecKeyOptions.getBuffer() method returns the PEM or secret key buffer. In releases prior to Eclipse Vert.x 4.0.2, the key buffer was stored and returned as a String. However, it is recommended to save secrets as a Buffer. From Eclipse Vert.x 4.0.2 onward, the method stores and returns the key buffer as a Buffer. This change improves the security and handling of secrets.

The PubSecKeyOptions.setBuffer() method continues to accept a String argument. In the set method, an overload for Buffer has been added to safely handle non ASCII secret materials. This change does not require any change to the existing code.

From Eclipse Vert.x 4, the KubernetesServiceImporter discovery bridge is no longer registered automatically. Even if you have added the bridge in the classpath of your Maven project, it will not be automatically registered.

You must manually register the bridge after creating the ServiceDiscovery instance.

Eclipse Vert.x 4 uses futures for asynchronous operations. Every callback method has a corresponding future method.

Futures can be used to compose asynchronous operations. When you use futures, the error handling is better. Therefore, it is recommended to use a combination of callback and futures in your applications.

In Eclipse Vert.x 4, Jackson Databind is an optional Maven dependency. If you want to use this dependency, you must explicitly add it in the classpath. For example, if you are object mapping JSON, then you must explicitly add the dependency.

In Eclipse Vert.x 4, new enhanced features have been provided. The old features and functions have been deprecated or removed in Eclipse Vert.x 4. Before you migrate your applications to Eclipse Vert.x 4, check for deprecations and removals.

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

Eclipse Vert.x 4 supports distributed tracing. You can use tracing to monitor microservices and identify performance issues.

Eclipse Vert.x 4 integrates with OpenTracing system.

The following Eclipse Vert.x components can log traces:

In Eclipse Vert.x 4, the EventBus JavaScript client, vertx-web-client.js is not published as a Red Hat artifact in the Maven repository.

The client is published in the npm repository. You can access the client from the following location: @vertx/eventbus-bridge-client.js

Use the OpenShift Maven plugin to deploy your Eclipse Vert.x applications on OpenShift. The Fabric8 Maven plugin is no longer supported. For more information, see the section migrating from Fabric8 Maven Plugin to Eclipse JKube.

You can add metering labels to your Eclipse Vert.x pods and check Red Hat subscription details with the OpenShift Metering Operator.

Eclipse Vert.x should use the following metering labels:

Eclipse Vert.x introduces support for building and deploying Eclipse Vert.x applications to OpenShift with OCI-compliant Universal Base Images for Red Hat OpenJDK 8 and Red Hat OpenJDK 11 on RHEL 8.

The RHEL 8 OpenJDK Universal Base Images replace the RHEL 8 OpenJDK builder images. The RHEL 8 OpenJDK base images are no longer supported for use with Eclipse Vert.x.