Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updating/augmenting JPMS documentation included in PR #2934

This commit is contained in:
WalkerWatch 2018-10-11 14:08:24 -04:00
parent 29c51091c7
commit 68911c54fb
2 changed files with 34 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
jetty-documentation/src/main/asciidoc/administration/startup/custom-modules.adoc
View File

@ -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

96
jetty-documentation/src/main/asciidoc/administration/startup/startup-jpms.adoc
View File

@ -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: