README.adoc

Vert.x JPMS examples

Here you will find examples demonstrating how Vert.x can be used with the Java Platform Module System (JPMS).

You can run tests from IDE or from an application image generated by jlink.

An application image is generated by the Apache Maven JLink Plugin when packaging the project with Maven (notice the jlink package in pom.xml), you can find the image in target/maven-jlink/default

Warning

Running these examples from your IDE might not work sometimes due to JPMS / IDE discrepancies. We recommend loading this Maven module io.vertx:jpms-examples directly in your IDE instead of io.vertx:vertx-examples.

HTTP/1.1 Server

A simple HTTP/1.1 server

You can run the server in your IDE and then curl http://localhost:8080.

You can also run the application image:

./target/maven-jlink/default/bin/java --module jpms.examples/io.vertx.example.jpms.http.Server

The Maven JLink plugin creates a launcher

./target/maven-jlink/default/bin/http-server

OSX native dns resolver

OSX can use an optional native DNS resolver that improves DNS resolution.

This is visible when running jlink with the following log:

Mar 24, 2026 11:17:36 AM io.netty.resolver.dns.DnsServerAddressStreamProviders <clinit>
WARNING: Can not find io.netty.resolver.dns.macos.MacOSDnsServerAddressStreamProvider in the classpath, fallback to system defaults. This may result in incorrect DNS resolutions on MacOS. Check whether you have a dependency on 'io.netty:netty-resolver-dns-native-macos'

This can be resolved by adding the following runtime option -add-modules io.netty.resolver.dns.classes.macos,io.netty.resolver.dns.macos.osx.aarch_64, here is an example for M1 architecture:

/target/maven-jlink/default/bin/java --add-modules io.netty.resolver.dns.classes.macos,io.netty.resolver.dns.macos.osx.aarch_64 --module jpms.examples/io.vertx.example.jpms.http.Server

Note	you can add this to your module-info.java declaration and omit the --add-modules declaration

HTTP/2 Server

A simple HTTP/2 server

You can run the server in your IDE and then curl -k https://localhost:8443.

You can also run the application image:

./target/maven-jlink/default/bin/java ---module jpms.examples/io.vertx.example.jpms.http2.Server

Or use the launcher:

./target/maven-jlink/default/bin/http2-server

HTTP compression

A HTTP/1.1 server with Brotli compression.

You can test the server with:

> curl -sH 'Accept-encoding: br' http://localhost:8080 | brotli -c -d

You can also run the application image:

./target/maven-jlink/default/bin/java --module jpms.examples/io.vertx.example.jpms.compression.Server

Or use the launcher:

./target/maven-jlink/default/bin/http-server-with-compression

gRPC Service

A simple gRPC service

To run this example, you need to set the env variable TEMPORARILY_DISABLE_PROTOBUF_VERSION_CHECK to true because the project uses a modified JPMS compliant Protobuf/Guava versions from JPMS Attic Repository.

You can run the server in your IDE and then grpcurl -plaintext -d '{"name":"Julien"}' -proto src/main/proto/helloworld.proto localhost:8080 helloworld.Greeter/SayHello.

You can also run the application image:

# Required because we use 4.26.1-jpms dependency
export TEMORARILY_DISABLE_PROTOBUF_VERSION_CHECK=true # yes there is a typo ...

./target/maven-jlink/default/bin/java --module jpms.examples/io.vertx.example.jpms.grpc.Server

Or use the launcher:

./target/maven-jlink/default/bin/grpc-server

You can use gRPCurl to interact with the server and its hosted services:

> grpcurl -plaintext localhost:8080 list
grpc.reflection.v1.ServerReflection
helloworld.Greeter

> grpcurl -plaintext localhost:8080 list helloworld.Greeter
helloworld.Greeter.SayHello

> grpcurl -plaintext -d '{"name":"Julien"}' localhost:8080 helloworld.Greeter.SayHello
{
  "message": "Hello Julien"
}

Native transports

A simple HTTP server running with Netty native transports kqueue/epoll/io_uring.

To run this example in the IDE, you need to add transport/OS/architecture specific modules:

• it can be added to the module-info.java declarations

• io.netty.transport.classes.${native.transport}

• io.netty.transport.${native.transport}.${os.detected.name}.${os.detected.arch}

• or to the JVM launch command: --add-modules io.netty.transport.classes.${native.transport},io.netty.transport.${native.transport}.${os.detected.name}.${os.detected.arch}

You can also run the application image (Mac/M1):

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

Or launch the JVM with --add-modules io.netty.transport.classes.kqueue,io.netty.transport.kqueue.osx.aarch_64:

./target/maven-jlink/default/bin/java --add-modules io.netty.transport.classes.kqueue,io.netty.transport.kqueue.osx.aarch_64 --module jpms.examples/io.vertx.example.jpms.native_transport.Server

Open SSL

A simple HTTP server using Netty OpenSSL.

To run this example in the IDE, you need to add OS/architecture specific modules:

• it can be added to the module-info.java declarations

• io.netty.tcnative.classes.openssl

• io.netty.internal.tcnative.openssl.${os.detected.name}.${os.detected.arch}

• or to the JVM launch command: --add-modules io.netty.transport.classes.${native.transport},io.netty.transport.${native.transport}.${os.detected.name}.${os.detected.arch}

You can also run the application image (Mac/M1):

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

Or launch a JVM with --add-modules io.netty.tcnative.classes.openssl,io.netty.internal.tcnative.openssl.osx.aarch_64:

./target/maven-jlink/default/bin/java --add-modules io.netty.tcnative.classes.openssl,io.netty.internal.tcnative.openssl.osx.aarch_64 --module jpms.examples/io.vertx.example.jpms.openssl.Server

Sql Client

A simple client accessing the PostgreSQL database.

Since it requires a database, you can run it from a JUnit5 test

Service Proxy

A simple service proxy example.

Sql Client Template

An SQL client template.