Starting Jetty using JPMS

The main advantage of running Jetty in JPMS mode is that it provides early error reporting if a dependency is missing, especially in case of custom Jetty modules.

If a Jetty module requires a specific library *.jar file, and the *.jar file is missing, this will be detected early when running in JPMS mode, since the *.jar file would be a JPMS module, and the JPMS module graph resolution would detect this problem as the JVM starts up. When running in class-path mode, this problem can only be detected when the library classes are loaded, therefore much later at run-time, when an HTTP request arrives and its processing requires to load the library classes.

Similarly, duplicate *.jar files, of possibly different versions, are not allowed by JPMS. This is again detected early, at JVM startup, when running in JPMS mode, rather than passing completely unnoticed when running in class-path mode, where classes may be loaded from either of those *.jar files, possibly from the wrong version.

Another advantage of running Jetty in JPMS mode is that JPMS provides strong encapsulation. This means that it is not possible to use reflection to access non-exported classes in JPMS modules within the ModuleLayer hierarchy. This is enforced at the JVM level, not at the application level through, for example, a custom ClassLoader that performs class loading filtering.

It also means that it is not possible to use reflection to access sibling ModuleLayers. For example a Jakarta EE 9 web application would not be able to use reflection to access a sibling Jakarta EE 10 web application.

When the Jetty server is started in JPMS mode, there will be two JVMs: one started by you with java -jar $JETTY_HOME/start.jar and one forked by the Jetty start mechanism.

The forked JVM is started with java --module-path $JETTY_HOME/lib/jetty-server-<version>.jar:..., and therefore has the server libraries in its module-path, loaded by the System ClassLoader, in the boot ModuleLayer:

When a Jakarta EE Jetty module is enabled, for example the ee10-webapp and/or the ee10-deploy module, the forked JVM is configured as follows:

Note how the parent of the Jetty EE 10 ClassLoader is the System ClassLoader, and how the parent of the Jetty EE 10 ModuleLayer is the Boot ModuleLayer.

When different versions of the Jakarta EE Jetty modules are enabled, the forked JVM is configured as follows:

Note how the Jetty EE ClassLoaderss are siblings, and both have the System ClassLoader as parent. Note also how the Jetty EE ModuleLayers are siblings, and both have the Boot ModuleLayer as parent.

Web applications may need additional services from the Servlet Container, such as JDBC DataSource references or JTA UserTransaction references.

For example, for JDBC it is typical to store, in JNDI, a reference to the connection pool’s DataSource or directly a reference to the JDBC driver’s DataSource (for example, org.postgresql.ds.PGConnectionPoolDataSource). Jetty needs to be able to instantiate those classes and therefore needs to be able to load those classes and all their super-classes, among which includes javax.sql.DataSource.

When Jetty runs on the class-path, this is easily achieved by using a custom module as explained in this section.

However, when running on the module-path, things are quite different.

When Jetty tries to load, for example, class org.postgresql.ds.PGConnectionPoolDataSource, it must be in a JPMS module that is resolved in the run-time module graph. Furthermore, any dependency, for example classes from the java.sql JPMS module, must also be in a module present in the resolved module graph.

Thanks to the fact that when Jetty starts in JPMS mode the --add-modules=ALL-MODULE-PATH option is added to the JVM command line, every *.jar file in the module-path is also present in the module graph.

There are now two cases for the postgresql-<version>.jar file: either it is a proper JPMS module, or it is an automatic JPMS module (either an explicit automatic JPMS module with the Automatic-Module-Name attribute in the manifest, or an implicit automatic JPMS module whose name is derived from the *.jar file name).

If the postgresql-<version>.jar file is a proper JPMS module, then there is nothing more that you should do: the postgresql-<version>.jar file is in the module-path, and all the modules in the module-path are in the module graph (thanks to --add-modules=ALL-MODULE-PATH), and any dependency declared in the module-info.class will be added to the module graph.

Otherwise, postgresql-<version>.jar file is an automatic module, and will likely have a dependency on the JDK-bundled java.sql JPMS module. Fortunately, when Jetty starts in JPMS mode, the --add-modules=ALL-DEFAULT option is also added to the JVM command line, so that all the Java JPMS modules are added to the module graph, and this would include the java.sql JPMS module.

Thanks to the fact that Jetty starts by default adding --add-modules=ALL-DEFAULT,ALL-MODULE-PATH, it is enough that you put custom libraries (and their dependencies) in the module-path, and you should not need any extra JPMS configuration.

However, you can explicitly configure JPMS directives in a custom Jetty module, for example to open or patch a JPMS module. Using the postgresql.mod introduced in this section as an example, modify your custom Jetty module and add the JPMS directives you need, like so:

The Jetty JPMS directives are equivalent to the JDK JPMS directives.

The [jpms] section is only used when Jetty is started on the module-path.