Advanced

Modular Vert.x Guide

Starting 5, Vert.x supports building modular applications and services with the Vert.x stack.

This document aims to guide the developer toward building and running a modular applications with Vert.x.

Definitions

We borrow terminology from this document for the following names:

named module
explicit module
automatic module

Maturity model

Vert.x strives to deliver the most mature JPMS level support (see https://nipafx.dev/java-modules-jpms-maturity-model/).

Most Vert.x components support level 3 (according to the maturity model) and explicit modules, however a few modules have been left aside, due to constraints preventing proper modularity to happen, often due to a faulty dependency, e.g. a split package.

Native transports

Native transports are supported.

The module io.netty.transport.classes.${native.detected.transport} is required as it contains the transport classes.

The module io.netty.transport.${native.transport}.${os.name}.${os.detected.arch} contains the native library and its presence is only required at runtime.

You can add them to the JVM launch command with --add-modules --add-modules io.netty.transport.classes.${native.transport},io.netty.transport.${native.transport}.${os.detected.name}.${os.detected.arch}.

Alternatively you can also add them to your module descriptor (even though your application does not use them) which usually triggers tools to add them automatically at runtime, however this binds your module to a specific os/architecture:

// Add to module-info.java
requires io.netty.transport.classes.kqueue;
requires io.netty.transport.kqueue.osx.aarch_64;

You can find an example with OpenSSL among Vert.x JPMS examples.

OpenSSL

OpenSSL is supported.

The module io.netty.tcnative.classes.openssl is required as it contains the OpenSSL Netty classes.

The module io.netty.internal.tcnative.openssl.${os.detected.name}.${os.detected.arch} contains the native library and its presence is only required at runtime.

You can add them to the JVM launch command with --add-modules io.netty.transport.classes.${native.transport},io.netty.transport.${native.transport}.${os.detected.name}.${os.detected.arch}.

// Add to your module-info.java
requires io.netty.tcnative.classes.openssl;
requires io.netty.internal.tcnative.openssl.osx.aarch_64;

You can find an example with OpenSSL among Vert.x JPMS examples.

HTTP Compression

Vert.x supports gzip and deflate algorithms out of the box, however brotli and zstd algorithms requires you to respectively add the following dependencies:

Brotli: com.aayushatharva.brotli4j:brotli4j
Zstd: com.github.luben:zstd-jni

These dependencies are optional since not everyone need them and when used, they are required at runtime instead of compile time.

You can add them to the JVM launch command with --add-modules com.aayushatharva.brotli4j,com.github.luben.zstd_jni.

Alternatively you can also add them to your module descriptor (even though your application does not use them) which usually triggers tools to add them automatically at runtime.

// Add to your module-info.java
requires com.aayushatharva.brotli4j;
requires com.github.luben.zstd_jni;

You can find an example with Brotli among Vert.x JPMS examples.

Code generation

Code generation of a modular application is supported.

The following module are available for applications:

Artifact ID

Module name

Description

vertx-codegen-api

io.vertx.codegen.api

Codegen annotations, e.g. io.vertx.codegen.annotations.DataObject

vertx-codegen-json

io.vertx.codegen.json

JSON generator API, e.g. io.vertx.codegen.json.JsonGen

Your application requires these components on the module path.

The Vert.x 4 vertx-codegen component has been split between

vertx-codegen-processor contains the annotation processor only necessary to the Java compiler
vertx-codegen-api contains the annotations
vertx-codegen-json contains the json generator

vertx-codegen still exists for backward compatibility purpose, feel free to use it or use finer grained dependencies.

Service proxy generation

Here is the bare minimum required by your module to generate a service proxy.

// Service proxy
requires static io.vertx.codegen.api;
requires static io.vertx.codegen.json;

You can find the service proxy example among our set of examples.

Sql Client Template generation

Todo (needs https://github.com/vert-x3/vertx-examples/pull/474/files)

Components

Core

Artifact ID Module name Dependencies

Artifact ID	Module name	Dependencies
vertx-core	`io.vertx.core`	explicit
vertx-core-logging	`io.vertx.core.logging`	explicit

vertx-core

io.vertx.core

explicit

vertx-core-logging

io.vertx.core.logging

explicit

Your application should never require io.vertx.core.logging, this module contains the logging abstraction used by Vert.x for logging purposes and is exclusively used by Vert.x components. Your application should use the logging framework of your choice and configure Vert.x logging to use it.

Dependencies

Transitive dependencies are explicit modules.

The Netty library io.netty:* (See Modular Netty)
The Jackson library com.fasterxml.jackson.core:*
Apache Log4j 2 org.apache.logging.log4j:*
SLF4J org.slf4j:*

Optional dependencies are explicit modules.

Brotli4j com.aayushatharva.brotli4j:brotli4j
Zstd-jni com.github.luben:zstd-jni

Auth

Artifact ID Module name Dependencies

Artifact ID	Module name	Dependencies
vertx-auth-common	`io.vertx.auth.common`	explicit
vertx-auth-htpasswd	`io.vertx.auth.htpasswd`	explicit
vertx-auth-abac	`io.vertx.auth.abac`	explicit
vertx-auth-ldap	`io.vertx.auth.ldap`	explicit
vertx-auth-sqlclient	`io.vertx.auth.sqlclient`	explicit
vertx-auth-oauth2	`io.vertx.auth.oauth2`	explicit
vertx-auth-htdigest	`io.vertx.auth.htdigest`	explicit
vertx-auth-jwt	`io.vertx.auth.jwt`	explicit
vertx-auth-properties	`io.vertx.auth.properties`	explicit
vertx-auth-webauthn4j	`io.vertx.auth.webauthn4j`	explicit
vertx-core-otp	`io.vertx.core.otp`	explicit

vertx-auth-common

io.vertx.auth.common

explicit

vertx-auth-htpasswd

io.vertx.auth.htpasswd

explicit

vertx-auth-abac

io.vertx.auth.abac

explicit

vertx-auth-ldap

io.vertx.auth.ldap

explicit

vertx-auth-sqlclient

io.vertx.auth.sqlclient

explicit

vertx-auth-oauth2

io.vertx.auth.oauth2

explicit

vertx-auth-htdigest

io.vertx.auth.htdigest

explicit

vertx-auth-jwt

io.vertx.auth.jwt

explicit

vertx-auth-properties

io.vertx.auth.properties

explicit

vertx-auth-webauthn4j

io.vertx.auth.webauthn4j

Artifact ID Module name Dependencies

Artifact ID	Module name	Dependencies
vertx-web-common	`io.vertx.web.common`	explicit
vertx-web	`io.vertx.web`	explicit
vertx-web-openapi-router	`io.vertx.web.openapi-router`	explicit
vertx-web-validation	`io.vertx.web.validation`	explicit
vertx-web-proxy	`io.vertx.web.proxy`	explicit
vertx-web-graphql	`io.vertx.web.graphql`	automatic
vertx-web-client	`io.vertx.web.client`	explicit
vertx-web-sstore-redis	`io.vertx.web.sstore.redis`	explicit
vertx-web-sstore-cookie	`io.vertx.web.sstore.cookie`	explicit
vertx-web-api-service	`io.vertx.web.apiservice`	explicit
vertx-web-template-mvel	`io.vertx.web.template.mvel`	automatic
vertx-web-template-freemarker	`io.vertx.web.template.freemarker`	automatic
vertx-web-template-thymeleaf	`io.vertx.web.template.thymeleaf`	automatic
vertx-web-template-rocker	`io.vertx.web.template.rocker`	automatic
vertx-web-template-handlebars	`io.vertx.web.template.handlebars`	automatic
vertx-web-template-jte	`io.vertx.web.template.jte`	automatic

vertx-web-common

io.vertx.web.common

explicit

vertx-web

io.vertx.web

explicit

vertx-web-openapi-router

io.vertx.web.openapi-router

explicit

vertx-web-validation

io.vertx.web.validation

explicit

vertx-web-proxy

io.vertx.web.proxy

explicit

vertx-web-graphql

io.vertx.web.graphql

automatic

vertx-web-client

io.vertx.web.client

explicit

vertx-web-sstore-redis

io.vertx.web.sstore.redis

explicit

vertx-web-sstore-cookie

io.vertx.web.sstore.cookie

explicit

vertx-web-api-service

io.vertx.web.apiservice

explicit

vertx-web-template-mvel

io.vertx.web.template.mvel

automatic

vertx-web-template-freemarker

io.vertx.web.template.freemarker

automatic

vertx-web-template-thymeleaf

io.vertx.web.template.thymeleaf

automatic

vertx-web-template-rocker

io.vertx.web.template.rocker

automatic

vertx-web-template-handlebars

io.vertx.web.template.handlebars

automatic

vertx-web-template-jte

io.vertx.web.template.jte

automatic

The following template engine do not support modularity at the moment:

vertx-web-template-httl
vertx-web-template-pebble
vertx-web-template-pug
vertx-web-template-rythm

SQL Client

Artifact ID

Module name

Dependencies

vertx-sql-client

io.vertx.sql.client

explicit

vertx-pg-client

io.vertx.sql.client.pg

explicit

vertx-mssql-client

io.vertx.sql.client.mssql

explicit

vertx-mysql-client

io.vertx.sql.client.mysql

explicit

vertx-pg-client

io.vertx.sql.client.pg

explicit

Artifact ID

Module name

Dependencies

vertx-config

io.vertx.config

explicit

vertx-config-git

io.vertx.config.git

automatic

vertx-config-hocon

io.vertx.config.hocon

automatic

vertx-config-configmap

io.vertx.config.configmap

explicit

vertx-config-spring

io.vertx.config.spring

explicit

vertx-config-yaml

io.vertx.config.yaml

explicit

vertx-config-consul

io.vertx.config.consul

explicit

vertx-config-redis

io.vertx.config.redis

explicit

Json Schema

Artifact ID

Module name

Dependencies

vertx-json-schema

io.vertx.jsonschema

explicit

Open API

Artifact ID

Module name

Dependencies

vertx-open-api

io.vertx.openapi

explicit

MQTT

Artifact ID

Module name

Dependencies

vertx-mqtt

io.vertx.mqtt

explicit

gRPC

Artifact ID

Module name

Dependencies

vertx-grpc-common

io.vertx.grpc.common

automatic

vertx-grpc-client

io.vertx.grpc.client

automatic

vertx-grpc-server

io.vertx.grpc.server

automatic

The following modules do not support modularity:

vertx-grpcio-common
vertx-grpcio-client
vertx-grpcio-server

Since Vert.x 5, the Vert.x gRPC stack is split in two

vertx-grpc-\* artifacts providing explicit modules, yet relying on com.google.protobuf and com.google.protobuf.util named automatic modules
vertx-grpc-io-* artifacts which cannot be modular, relying on the non-modular io.grpc:* artifacts

Concerning the com.google.protobuf.* artifacts, there is a modular version of it in the JPMS Attic Repository until the Java Protocol Buffers library supports it. Here is an example of a modular gRPC service.

JUnit 5

Artifact ID

Module name

Zipkin Tracing

Artifact ID

Module name

Dependencies

vertx-zipkin

io.vertx.tracing.zipkin

automatic