Jetty 12.0.x document modules

documentation/jetty-documentation/src/main/asciidoc/operations-guide/.asciidoctorconfig

@@ -1,5 +1,8 @@
 // Asciidoctor IDE configuration file.
 // See https://github.com/asciidoctor/asciidoctor-intellij-plugin/wiki/Support-project-specific-configurations
+:ee-all: ee{8,9,10}
+:ee-current: ee10
+:ee-current-caps: EE10
 :experimental:
 :imagesdir: images
 :JETTY_HOME: ../../../../../../../jetty-home/target/jetty-home

documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/deploy.adoc

@@ -46,46 +46,46 @@ mywebapp.war
 <5> `WEB-INF/web.xml` is the web application deployment descriptor, which defines the components and the configuration of your web application.
 ====
 
-To deploy a standard web application, you need to enable the xref:og-module-deploy[`deploy` module]:
+To deploy a standard web application, you need to enable the xref:og-module-eeN-deploy[`{ee-current}-deploy` module].
+
+NOTE: The following examples assume you're deploying a Jakarta {ee-current-caps} app; for other versions of EE, make sure to activate the corresponding `{ee-all}-deploy` module.
 
 ----
-$ java -jar $JETTY_HOME/start.jar --add-module=deploy
+$ java -jar $JETTY_HOME/start.jar --add-module={ee-current}-deploy
 ----
 
 [source,options=nowrap]
 ----
-include::jetty[setupArgs="--add-module=http",args="--add-module=deploy"]
+include::jetty[setupArgs="--add-module=http",args="--add-module={ee-current}-deploy"]
 ----
 
-The `deploy` module creates `$JETTY_BASE/webapps`, which is the directory where Jetty looks for any `+*.war+` files or web application directories to deploy.
+The `{ee-current}-deploy` module creates `$JETTY_BASE/webapps`, which is the directory where Jetty looks for any `+*.war+` files or web application directories to deploy.
 
-[NOTE]
-====
-Activating Jetty's `deploy` module enables web application deployment.
+Activating one of Jetty's `{ee-all}-deploy` modules enables web application deployment.
 Whether these web applications are served via clear-text HTTP/1.1, or secure HTTP/1.1, or secure HTTP/2, or HTTP/3 (or even all of these protocols) depends on if the correspondent Jetty modules have been enabled.
-
-Refer to the xref:og-protocols[section about protocols] for further information.
-====
+(Refer to the xref:og-protocols[section about protocols] for further information.)
 
 Now you're ready to copy a web application to the `$JETTY_BASE/webapps` directory.
 You can use one of the demos shipped with Jetty:
 
+[subs=attributes]
 ----
-$ java -jar $JETTY_HOME/start.jar --add-module=ee10-demo-simple
+$ java -jar $JETTY_HOME/start.jar --add-module={ee-current}-demo-simple
 ----
 
 The `$JETTY_BASE` directory is now:
 
+[subs=attributes]
 ----
 $JETTY_BASE
 ├── resources
 │   └── jetty-logging.properties
 ├── start.d
 │   ├── deploy.ini
-│   ├── ee10-demo-simple.ini
+│   ├── {ee-current}-demo-simple.ini
 │   └── http.ini
 └── webapps
-    └── ee10-demo-simple.war
+    └── {ee-current}-demo-simple.war
 ----
 
 Now start Jetty:
@@ -96,12 +96,12 @@ $ java -jar $JETTY_HOME/start.jar
 
 [source,subs=quotes,options=nowrap]
 ----
-include::jetty[setupArgs="--add-modules=http,deploy,ee10-demo-simple",highlight="WebAppContext"]
+include::jetty[setupArgs="--add-modules=http,deploy,{ee-current}-demo-simple",highlight="WebAppContext"]
 ----
 
-Note the highlighted line that logs the deployment of `ee10-demo-simple.war`.
+Note the highlighted line that logs the deployment of `{ee-current}-demo-simple.war`.
 
-Now you can access the web application by pointing your browser to `+http://localhost:8080/ee10-demo-simple+`.
+Now you can access the web application by pointing your browser to `pass:a[http://localhost:8080/{ee-current}-demo-simple]`.
 
 [[og-begin-deploy-war-advanced]]
 ===== Advanced Deployment

documentation/jetty-documentation/src/main/asciidoc/operations-guide/deploy/chapter.adoc

@@ -16,7 +16,7 @@
 
 Most of the times you want to be able to customize the deployment of your web applications, for example by changing the `contextPath`, or by adding JNDI entries, or by configuring virtual hosts, etc.
 
-The customization is performed by the xref:og-module-deploy[`deploy` module] by processing xref:og-deploy-jetty[Jetty context XML files].
+The customization is performed by the xref:og-module-eeN-deploy[`{ee-all}-deploy` module] by processing xref:og-deploy-jetty[Jetty context XML files].
 
 The `deploy` module contains the `DeploymentManager` component that scans the `$JETTY_BASE/webapps` directory for changes, following the deployment rules described in xref:og-deploy-rules[this section].
 

documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaas/chapter.adoc

@@ -36,10 +36,10 @@ own custom link:https://docs.oracle.com/javase/7/docs/api/javax/security/auth/sp
 [[og-jaas-module]]
 ===== The `jaas` module
 
-Enable the `ee{8,9,10}-jaas` module appropriate for your EE platform:
+Enable the `{ee-all}-jaas` module appropriate for your EE platform:
 
 ----
-include::{JETTY_HOME}/modules/ee10-jaas.mod[]
+include::{JETTY_HOME}/modules/{ee-current}-jaas.mod[]
 ----
 
 The configurable items in the resulting `$jetty.base/start.d/jaas.ini` file are:

documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc

@@ -27,28 +27,29 @@ Only modules conforming to the "Servlet Container Profile" with the ServerAuthMo
 Enable the `jaspi` module:
 
 ----
-include::{JETTY_HOME}/modules/ee10-jaspi.mod[]
+include::{JETTY_HOME}/modules/{ee-current}-jaspi.mod[]
 ----
 
 [[og-jaspi-xml]]
 ===== Configure JASPI
 
-Activate the `ee{9,10}-jaspi` module that matches your EE platform version.
+Activate either the `ee9-jaspi` or `{ee-current}-jaspi` module, whichever matches your EE platform version.
 
+[subs=attributes]
 ----
-$ java -jar $JETTY_HOME/start.jar --add-modules=ee10-jaspi
+$ java -jar $JETTY_HOME/start.jar --add-modules={ee-current}-jaspi
 ----
 
 You can then register a `AuthConfigProvider` onto the static `AuthConfigFactory` obtained with `AuthConfigFactory.getFactory()`. This registration can be done in the XML configuration file which will be copied to `$JETTY_BASE/etc/jaspi/jaspi-authmoduleconfig.xml` when the module is enabled.
 
 ====== JASPI Demo
-The `ee9-jaspi-demo` and `ee10-jaspi-demo` modules illustrate setting up HTTP Basic Authentication using the EE9 and EE10 Jakarta Authentication modules that come packaged with Jetty.
+The `ee9-jaspi-demo` and `{ee-current}-jaspi-demo` modules illustrate setting up HTTP Basic Authentication using the EE9 and {ee-current-caps} Jakarta Authentication modules that come packaged with Jetty.
 
-The following example uses Jetty's EE10 implementation of `AuthConfigProvider` to register a `ServerAuthModule` directly.
+The following example uses Jetty's {ee-current-caps} implementation of `AuthConfigProvider` to register a `ServerAuthModule` directly.
 
 [source, xml]
 ----
-include::{JETTY_HOME}/etc/jaspi/jetty-ee10-jaspi-demo.xml[]
+include::{JETTY_HOME}/etc/jaspi/jetty-{ee-current}-jaspi-demo.xml[]
 ----
 
 Other custom or 3rd party modules that are compatible with the `ServerAuthModule` interface in JASPI can be registered in the same way.
@@ -63,8 +64,8 @@ The `CallerPrincipalCallback` and `GroupPrincipalCallback` do not require use of
 
 Jetty provides an implementation of the `AuthConfigFactory` interface which is used to register `AuthConfigProviders`. This can be replaced by a custom implementation by adding a custom module which provides `auth-config-factory`.
 This custom module must reference an XML file which sets a new instance of the `AuthConfigFactory` with the static method `AuthConfigFactory.setFactory()`.
-For an example of this see the `ee{9,10}-jaspi-default-auth-config-factory` module, which provides the default implementation used by Jetty.
+For an example of this see the `{ee-current}-jaspi-default-auth-config-factory` module, which provides the default implementation used by Jetty.
 
 ----
-include::{JETTY_HOME}/modules/ee10-jaspi-default-auth-config-factory.mod[]
+include::{JETTY_HOME}/modules/{ee-current}-jaspi-default-auth-config-factory.mod[]
 ----

documentation/jetty-documentation/src/main/asciidoc/operations-guide/jmx/jmx-local.adoc

@@ -14,7 +14,7 @@
 [[og-jmx-local]]
 ==== Enabling Local JMX Support
 
-As with many other Jetty features, local JMX support is enabled with the `jmx` Jetty module:
+As with many other Jetty features, local JMX support is enabled with the xref:og-module-jmx[`jmx` Jetty module]:
 
 ----
 $ java -jar $JETTY_HOME/start.jar --add-module=jmx

documentation/jetty-documentation/src/main/asciidoc/operations-guide/jsp/chapter.adoc

@@ -14,10 +14,11 @@
 [[og-jsp]]
 === Java Server Pages
 
-Jetty supports JSP via the `ee{8,9,10}-jsp` modules, which are based on Apache Jasper:
+Jetty supports JSP via the `{ee-all}-jsp` modules, which are based on Apache Jasper:
 
+[subs=attributes]
 ----
-include::{JETTY_HOME}/modules/ee10-jsp.mod[]
+include::{JETTY_HOME}/modules/{ee-current}-jsp.mod[]
 ----
 
 Logging has been bridged to Jetty logging, so you can enable logging for the `org.apache.jasper` package, subpackages and classes as usual.
@@ -172,10 +173,11 @@ If the value you set doesn't take effect, try using all lower case instead of ca
 
 === JavaServer Pages Standard Tag Libraries
 
-The JavaServer Pages Standard Tag Library (JSTL) is part of the Jetty distribution, and is available via the `ee{8,9,10}-jstl` modules:
+The JavaServer Pages Standard Tag Library (JSTL) is part of the Jetty distribution, and is available via the `{ee-all}-jstl` modules:
 
+[subs=attributes]
 ----
-include::{JETTY_HOME}/modules/ee10-jstl.mod[]
+include::{JETTY_HOME}/modules/{ee-current}-jstl.mod[]
 ----
 
 When enabled, Jetty will make the JSTL tags available for your webapps.

documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-eeN-deploy.adoc

@@ -0,0 +1,38 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2022 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+[[og-module-eeN-deploy]]
+===== Module `{ee-all}-deploy`
+
+include::{JETTY_HOME}/modules/{ee-current}-deploy.mod[tags=description]
+
+Deployment is managed via a `DeploymentManager` component that watches a directory for changes.
+(See xref:og-deploy[how to deploy web applications] for more information.)
+
+Adding files or directories to this monitored directory will cause the `DeploymentManager` to deploy them as web applications; updating files already existing in this monitored directory will cause the `DeploymentManager` to re-deploy the corresponding web application; removing files in this monitored directory will cause the `DeploymentManager` to "undeploy" the corresponding web application.
+(You can find a more detailed discussion of these rules in the xref:og-deploy-rules[deployment rules] section.)
+
+Multiple versions of this module exist (`{ee-all}-deploy`) to support each EE platform's version of the Java Servlet specification.
+Jetty's configuration properties are nearly identical across these versions; the module file for `{ee-current}-deploy` is as follows:
+
+----
+include::{JETTY_HOME}/modules/{ee-current}-deploy.mod[tags=ini-template]
+----
+
+Among the configurable properties, the most relevant are:
+
+`jetty.deploy.monitoredDir`::
+The name of the monitored directory.
+`jetty.deploy.scanInterval`::
+The scan period in seconds, that is how frequently the `DeploymentManager` wakes up to scan the monitored directory for changes.
+Setting `jetty.deploy.scanInterval=0` disabled _hot_ deployment so that only static deployment will be possible (see also xref:og-deploy-hot-static[here] for more information).

documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-eeN-webapp.adoc

@@ -0,0 +1,26 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2022 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+[[og-module-eeN-webapp]]
+===== Module `{ee-all}-webapp`
+
+include::{JETTY_HOME}/modules/{ee-current}-webapp.mod[tags=description]
+
+If this module is not enabled, only Jetty-specific handlers may be deployed.
+
+Multiple versions of this module exist (`{ee-all}-webapp`) to support each EE platform's version of the Java Servlet specification.
+Jetty's configuration properties are identical across the `{ee-all}-` versions of this module, and are as follows:
+
+----
+include::{JETTY_HOME}/modules/{ee-current}-webapp.mod[tags=ini-template]
+----

documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-jmx.adoc

@@ -0,0 +1,20 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2022 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+[[og-module-jmx]]
+===== Module `jmx`
+
+include::{JETTY_HOME}/modules/{ee-current}-webapp.mod[tags=description]
+
+This configuration is useful for xref:og-jmx-local[local development and testing].
+If you need to xref:og-jmx-remote[enable remote access], use the xref:og-jmx-remote[`jmx-remote` module].

documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-standard.adoc

@@ -17,13 +17,14 @@
 include::module-alpn.adoc[]
 include::module-bytebufferpool.adoc[]
 include::module-console-capture.adoc[]
-include::module-deploy.adoc[]
+include::module-eeN-deploy.adoc[]
 include::module-http.adoc[]
 include::module-http2.adoc[]
 include::module-http2c.adoc[]
 include::module-http3.adoc[]
 include::module-http-forwarded.adoc[]
 include::module-https.adoc[]
+include::module-jmx.adoc[]
 include::module-jmx-remote.adoc[]
 include::module-requestlog.adoc[]
 include::module-server.adoc[]
@@ -32,4 +33,5 @@ include::module-ssl-reload.adoc[]
 include::module-test-keystore.adoc[]
 include::module-threadpool.adoc[]
 include::module-threadpool-virtual-preview.adoc[]
+include::module-eeN-webapp.adoc[]
 include::module-well-known.adoc[]

jetty-core/jetty-deploy/src/main/config/modules/deploy.mod

@@ -1,5 +1,5 @@
 [description]
-Enables web application deployment from the $JETTY_BASE/webapps/ directory.
+This module enables webapp deployment from the `$JETTY_BASE/webapps/` directory.
 
 [depend]
 server

jetty-core/jetty-jmx/src/main/config/modules/jmx.mod

@@ -1,5 +1,7 @@
 [description]
-Enables local JMX support for Jetty components.
+# tag::description[]
+This module enables local Java Management Extension (JMX) support for Jetty components.
+# end::description[]
 
 [depend]
 server

jetty-ee10/jetty-ee10-webapp/src/main/config/modules/ee10-deploy.mod

@@ -1,5 +1,7 @@
 [description]
-Enables web application deployment from the $JETTY_BASE/webapps/ directory.
+# tag::description[]
+This module enables webapp deployment from the `$JETTY_BASE/webapps/` directory.
+# end::description[]
 
 [environment]
 ee10
@@ -17,6 +19,7 @@ webapps/
 etc/jetty-ee10-deploy.xml
 
 [ini-template]
+# tag::ini-template[]
 ## Monitored directory name (relative to $jetty.base)
 # jetty.deploy.monitoredDir=webapps
 ## - OR -
@@ -52,3 +55,4 @@ etc/jetty-ee10-deploy.xml
 
 ## Order of discovered ServletContainerInitializers
 # jetty.deploy.servletContainerInitializerOrder=
+# end::ini-template[]

jetty-ee10/jetty-ee10-webapp/src/main/config/modules/ee10-webapp.mod

@@ -1,8 +1,9 @@
 # DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
 
 [description]
-Adds support for servlet specification web applications to the server classpath.
-Without this, only Jetty-specific handlers may be deployed.
+# tag::description[]
+This module enables deployment of Java Servlet web applications.
+# end::description[]
 
 [environment]
 ee10
@@ -18,6 +19,7 @@ etc/jetty-ee10-webapp.xml
 lib/jetty-ee10-webapp-${jetty.version}.jar
 
 [ini-template]
+# tag::ini-template[]
 ## Add to the server wide default jars and packages protected or hidden from webapps.
 ## System classes are protected and cannot be overridden by a webapp.
 ## Server classes are hidden and cannot be seen by a webapp
@@ -32,6 +34,7 @@ lib/jetty-ee10-webapp-${jetty.version}.jar
 ##
 #jetty.webapp.addSystemClasses+=,org.example.
 #jetty.webapp.addServerClasses+=,org.example.
+# end::ini-template[]
 
 [ini]
 contextHandlerClass?=org.eclipse.jetty.ee10.webapp.WebAppContext