Update JPMS readme

jpms-examples/README.adoc

@@ -2,7 +2,113 @@
 
 Here you will find examples demonstrating how Vert.x can be used with the Java Platform Module System (JPMS).
 
-This project contains several examples you can run in the IDE.
+You can run tests from IDE or from an application image generated by https://dev.java/learn/jlink/[jlink].
 
-- http2: a simple HTTP/2 link:src/main/java/io/vertx/examples/jpms/http2/Server.java[server]
+An application image is generated by the https://maven.apache.org/plugins/maven-jlink-plugin/[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`
 
+NOTE: the `io.netty.resolver.dns.classes.macos` and `io.netty.resolver.dns.macos.osx.aarch_64` are only use
+
+== HTTP/1.1 Server
+
+A simple HTTP/1.1 link:src/main/java/io/vertx/example/jpms/http/Server.java[server]
+
+You can run the server in your IDE and then `curl http://localhost:8080`.
+
+You can also run the application image (Mac/M1):
+
+[source,shell]
+----
+./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
+----
+
+== HTTP/2 Server
+
+A simple HTTP/1.1 link:src/main/java/io/vertx/example/jpms/http2/Server.java[server]
+
+You can run the server in your IDE and then `curl -k https://localhost:8443`.
+
+You can also run the application image (Mac/M1):
+
+[source,shell]
+----
+./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.http2.Server
+----
+
+== gRPC Server
+
+A simple gRPC link:src/main/java/io/vertx/example/jpms/grpc/Server.java[server]
+
+To run this example, you need to set the env variable `TEMORARILY_DISABLE_PROTOBUF_VERSION_CHECK` to `true` because the project uses a modified JPMS compliant Protobuf/Guava versions from https://github.com/elide-dev/jpms[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 (Mac/M1):
+
+[source,shell]
+----
+# 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 --add-modules io.netty.resolver.dns.classes.macos,io.netty.resolver.dns.macos.osx.aarch_64 --module jpms.examples/io.vertx.example.jpms.grpc.Server
+----
+
+== Native transports
+
+A simple HTTP link:src/main/java/io/vertx/example/jpms/http2/Server.java[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):
+
+[source,java]
+----
+// 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`:
+
+[source,shell]
+----
+./target/maven-jlink/default/bin/java --add-modules io.netty.resolver.dns.classes.macos,io.netty.resolver.dns.macos.osx.aarch_64,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 link:src/main/java/io/vertx/example/jpms/http2/Server.java[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):
+
+[source,java]
+----
+// 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`:
+
+[source,shell]
+----
+./target/maven-jlink/default/bin/java --add-modules io.netty.resolver.dns.classes.macos,io.netty.resolver.dns.macos.osx.aarch_64,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 link:src/main/java/io/vertx/example/jpms/sqlclient/Client.java[client] accessing the PostreSQL database.
+
+Since it requires a database, you can run it from a link:src/test/java/io/vertx/example/jpms/tests/SqlClientTest.java[JUnit5 test]

jpms-examples/src/main/java/io/vertx/example/jpms/native_transport/Server.java

@@ -15,8 +15,7 @@ public static void main(String[] args) {
  Vertx vertx = Vertx.vertx(new VertxOptions()
  .setPreferNativeTransport(true));
  if (!vertx.isNativeTransportEnabled()) {
- vertx.unavailableNativeTransportCause().printStackTrace();
- throw new RuntimeException(vertx.unavailableNativeTransportCause());
+ throw new RuntimeException("Add your OS/arch specific modules (explained in README)");
  }
  vertx.deployVerticle(new Server())
  .onFailure(Throwable::printStackTrace);

jpms-examples/src/main/java/module-info.java

@@ -9,9 +9,8 @@
  requires io.vertx.client.sql.pg;
  requires java.sql;
 
- // Is that actually necessary
- requires com.ongres.scram.client;
- requires com.ongres.scram.common;
+ requires io.netty.tcnative.classes.openssl;
+ requires io.netty.internal.tcnative.openssl.osx.aarch_64;
 
  requires com.google.protobuf;
 

jpms-examples/src/test/java/io/vertx/examples/jpms/tests/SqlClientTest.java → jpms-examples/src/test/java/io/vertx/example/jpms/tests/SqlClientTest.java

@@ -1,4 +1,4 @@
-package io.vertx.examples.jpms.tests;
+package io.vertx.example.jpms.tests;
 
 import io.vertx.core.Vertx;
 import io.vertx.core.buffer.Buffer;