diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/custom-modules.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/custom-modules.adoc index e070669d1be..dff59d79315 100644 --- a/jetty-documentation/src/main/asciidoc/administration/startup/custom-modules.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/startup/custom-modules.adoc @@ -79,6 +79,8 @@ If a user does not accept the license agreement, the module will not be activate Additional Startup Commands - `[exec]`:: The `[exec]` section is used to define additional parameters specific to the module. These commands are added to the server startup. +JPMS Module-Path Definitions - `[jpms]`:: +The `[jpms]` section is used to add link:#startup-jpms[JPMS modules] to the module-path for startup when using the `--jpms` command. [[custom-module-properties]] ==== Module Properties diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/startup-jpms.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/startup-jpms.adoc index b6fdb7b9671..075b75d9c96 100644 --- a/jetty-documentation/src/main/asciidoc/administration/startup/startup-jpms.adoc +++ b/jetty-documentation/src/main/asciidoc/administration/startup/startup-jpms.adoc @@ -16,29 +16,24 @@ // ======================================================================== // -[[startup-overview]] +[[startup-jpms]] === Startup using the Java Platform Module System (JPMS) -Jetty modules are also automatic https://en.wikipedia.org/wiki/Java_Platform_Module_System[JPMS] -modules via the `Automatic-Module-Name` attribute in the jar's `MANIFEST.MF` file. +Jetty modules also act ass automatic https://en.wikipedia.org/wiki/Java_Platform_Module_System[JPMS] modules via the `Automatic-Module-Name` attribute in the jar's `MANIFEST.MF` file. This makes possible to run Jetty from the module-path, rather than the class-path. -We recommend to use JDK 11 or greater due to the fact that JDK 11 removed all the -"enterprise" modules from the JDK. -The classes in these "enterprise" modules were bundled with JDK 8, and present in -"enterprise" modules in JDK 9 and JDK 10. -With JDK 11, these "enterprise" classes are either not available in the JDK (because -their corresponding module was removed), or they are present in a different module. +We recommend using JDK 11 or greater due to the fact that JDK 11 removed all the "enterprise" modules from the JDK. +The classes in these "enterprise" modules were bundled with JDK 8, and present in "enterprise" modules in JDK 9 and JDK 10. +With JDK 11, these "enterprise" classes are either not available in the JDK (because their corresponding module was removed), or they are present in a different module. -Some of these "enterprise" classes are required by Jetty or by applications running -in Jetty, so it is better to use a stable source for those classes by using JDK 11 +Because some of these "enterprise" classes are required by Jetty or by applications running in Jetty, it is better to use a stable source for those classes - in this case by using JDK 11 or greater. +[[jpms-module-path]] ==== Starting Jetty on the module-path -To start Jetty on the module-path, rather than the class-path, it is enough to add -the `--jpms` option to the command line, for example: +To start Jetty on the module-path rather than the class-path, it is enough to add the `--jpms` option to the command line, for example: [source, screen, subs="{sub-order}"] .... @@ -52,28 +47,24 @@ INFO : Base directory was modified $ java -jar $JETTY_HOME/start.jar --jpms .... -The example above creates a link:#startup-base-and-home[Jetty base directory] and -enables the `http` module using `--add-to-start`. -Then starts Jetty on the module-path using the `--jpms` option. +The example above creates a link:#startup-base-and-home[Jetty base directory] and enables the `http` module using the `--add-to-start` command. +The server then starts Jetty on the module-path using the `--jpms` option. ---- [NOTE] -When running on the module-path using the `--jpms` option, the Jetty start mechanism -will fork a second JVM passing it the right JVM options to run on the module-path. +When running on the module-path using the `--jpms` option, the Jetty start mechanism will fork a second JVM passing it the right JVM options to run on the module-path. -You will have two JVMs running: one that runs `start.jar` and one that runs Jetty on -the module-path. +You will have two JVMs running: one that runs `start.jar` and one that runs Jetty on the module-path. ---- -If you are interested in the details of how the command line to run Jetty on the -module-path looks like, you can add the `--dry-run` option: +If you are interested in the details of how the command line to run Jetty on the module-path looks like, you can add the `--dry-run` option: [source, screen, subs="{sub-order}"] .... $ java -jar $JETTY_HOME/start.jar --jpms --dry-run .... -You will see something like this (broken in sections for clarity): +This will give an out put looking something like this (broken in sections for clarity): [source, screen, subs="{sub-order}"] .... @@ -83,37 +74,25 @@ You will see something like this (broken in sections for clarity): --module org.eclipse.jetty.xml/org.eclipse.jetty.xml.XmlConfiguration /opt/jetty/etc/jetty-threadpool.xml /opt/jetty/etc/jetty.xml ... .... -The `--module-path` option specifies the list of Jetty jars. This list depends -on the Jetty modules that have been enabled via `--add-to-start`. +The `--module-path` option specifies the list of Jetty jars. +This list depends on the Jetty modules that have been enabled via the link:#startup-modules[`--add-to-start`] command. -The `--patch-module` option is necessary for Servlet and JSP Containers to find XML DTDs -and XML Schemas required to validate the various XML files present in web applications -(such as `web.xml` and others). +The `--patch-module` option is necessary for Servlet and JSP Containers to find XML DTDs and XML Schemas required to validate the various XML files present in web applications (such as `web.xml` and others). -The `--module` option tells the JVM to run main class `XmlConfiguration` from the -`org.eclipse.jetty.xml` module, with the given XML files as program arguments. +The `--module` option tells the JVM to run main class `XmlConfiguration` from the `org.eclipse.jetty.xml` module, with the given XML files as program arguments. -When the JVM starts, module `org.eclipse.jetty.xml` is added to the set of JPMS -_root modules_; all other Jetty modules, being automatic, will be resolved and added -to the module graph; jars that are not modules such as `servlet-api-3.1.jar` are on -the module-path and therefore will be made automatic modules by the JVM (hence the -derived module name `servlet.api` for this jar, referenced by the `--patch-module` -command line option above). +When the JVM starts, module `org.eclipse.jetty.xml` is added to the set of JPMS _root modules_; all other Jetty modules, being automatic, will be resolved and added to the module graph. +JAR files that are not modules, such as `servlet-api-3.1.jar`, are on the module-path and therefore will be made automatic modules by the JVM (hence the derived module name `servlet.api` for this jar, referenced by the `--patch-module` command line option above). +[[jpms-advanced-config]] ==== Advanced JPMS Configuration -Web applications may need additional services from the Servlet Container, such as -JDBC `DataSource` references or JTA `UserTransaction` references. +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` (for example `com.zaxxer.hikari.HikariDataSource`) or a -reference directly to the JDBC driver's `DataSource` (for example -`com.mysql.jdbc.jdbc2.optional.MysqlDataSource`). -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 `javax.sql.DataSource`. +For example, for JDBC it is typical to store, in JNDI, a reference to the connection pool's `DataSource` (such as `com.zaxxer.hikari.HikariDataSource`) or a reference directly to the JDBC driver's `DataSource` (`com.mysql.jdbc.jdbc2.optional.MysqlDataSource`). +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 -link:#custom-modules[custom module]: +When Jetty runs on the class-path, this is easily achieved by using a link:#custom-modules[custom module]: [source, screen, subs="{sub-order}"] .mysql.mod @@ -127,13 +106,10 @@ lib/mysql/mysql-connector-java-*.jar However, when running on the module-path, things are quite different. -Class `javax.sql.DataSource` is in a JDK bundled module named `java.sql`, which is -not automatic (it's a proper JPMS module) and it is not in the _root modules_ set; -because it is not an automatic module, it is not added to the module graph, and -therefore needs to be added explicitly using the JVM command line `--add-modules`. +Class `javax.sql.DataSource` is in a JDK bundled module named `java.sql`, which is not automatic (it's a proper JPMS module) and it is not in the _root modules_ set. +Because it is not an automatic module, it is not added to the module graph, and therefore needs to be added explicitly using the JVM command line `--add-modules`. -To add the JPMS module `java.sql` to the module graph, you need to modify -`mysql.mod` in the following way: +To add the JPMS module `java.sql` to the module graph, you need to modify your custom module in the following way, using our `mysql.mod` as an example: [source, screen, subs="{sub-order}"] .mysql.mod @@ -148,17 +124,11 @@ lib/mysql/mysql-connector-java-*.jar add-modules: java.sql .... -The new `[jpms]` section is only used when Jetty is started on the module-path -via the `--jpms` command line option. +The new `[jpms]` section is only used when Jetty is started on the module-path via the `--jpms` command line option. -Assuming that `mysql-connector-java-*.jar` is a non JPMS modular jar, or an -automatic JPMS modular jar, the Jetty start mechanism will add -`mysql-connector-java-*.jar` to the module-path, and will add the JVM command -line option `--add-modules java.sql`. +Assuming that `mysql-connector-java-*.jar` is a non JPMS modular jar, or an automatic JPMS modular jar, the Jetty start mechanism will add `mysql-connector-java-*.jar` to the module-path, and will add the JVM command line option `--add-modules java.sql`. -If `mysql-connector-java-*.jar` were a proper JPMS modular jar with name -(for example) `com.mysql.jdbc`, then it would need to be explicitly added to -the module graph, in this way: +If `mysql-connector-java-*.jar` were a proper JPMS modular jar with name (for example) `com.mysql.jdbc`, then it would need to be explicitly added to the module graph, in this way: [source, screen, subs="{sub-order}"] .mysql.mod @@ -173,9 +143,7 @@ lib/mysql/mysql-connector-java-*.jar add-modules: com.mysql.jdbc .... -Now we don't need to add JPMS module `java.sql` explicitly because it would be -a dependency of the `com.mysql.jdbc` module and therefore automatically added -to the module graph. +The JPMS module `java.sql` does not need to be explicitly added because it would be a dependency of the `com.mysql.jdbc` module and therefore automatically added to the module graph. The `[jpms]` section has the following format: