Merge branch 'jetty-9.4.x' into jetty-10.0.x

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

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]
+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.
-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
+We recommend using JDK 11 or greater due to the fact that JDK 11 removed all the "enterprise" modules from the JDK.
-"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.
-The classes in these "enterprise" modules were bundled with JDK 8, and present in
+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.
-"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
+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
-in Jetty, so it is better to use a stable source for those classes 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
+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:
-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
+The example above creates a link:#startup-base-and-home[Jetty base directory] and enables the `http` module using the `--add-to-start` command.
-enables the `http` module using `--add-to-start`.
+The server then starts Jetty on the module-path using the `--jpms` option.
-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
+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.
-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
+You will have two JVMs running: one that runs `start.jar` and one that runs Jetty on the module-path.
-the module-path.
 ----
 
-If you are interested in the details of how the command line to run Jetty on the
+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:
-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
+The `--module-path` option specifies the list of Jetty jars. 
-on the Jetty modules that have been enabled via `--add-to-start`.
+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
+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).
-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
+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.
-`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
+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.
-_root modules_; all other Jetty modules, being automatic, will be resolved and added
+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).
-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).
 
+[[jpms-advanced-config]]
 ==== Advanced JPMS Configuration
 
-Web applications may need additional services from the Servlet Container, such as
+Web applications may need additional services from the Servlet Container, such as JDBC `DataSource` references or JTA `UserTransaction` references.
-JDBC `DataSource` references or JTA `UserTransaction` references.
 
-For example, for JDBC it is typical to store in JNDI a reference to the connection
+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`).
-pool's `DataSource` (for example `com.zaxxer.hikari.HikariDataSource`) or a
+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`.
-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`.
 
-When Jetty runs on the class-path, this is easily achieved by using a
+When Jetty runs on the class-path, this is easily achieved by using a link:#custom-modules[custom module]:
-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
+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.
-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`.
-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
+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:
-`mysql.mod` in the following way:
 
 [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
+The new `[jpms]` section is only used when Jetty is started on the module-path via the `--jpms` command line option.
-via the `--jpms` command line option.
 
-Assuming that `mysql-connector-java-*.jar` is a non JPMS modular jar, or an
+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`.
-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
+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:
-(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
+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.
-a dependency of the `com.mysql.jdbc` module and therefore automatically added
-to the module graph.
 
 The `[jpms]` section has the following format: