Jetty 12.0.x document modules (#9151)

* Add documentation in "Standard Modules" section for the jmx module
* Add documentation in "Standard Modules" section for the ee8,9,10-webapp modules
* Use shorter markup tags to transclude documentation from .mod files
* Extract EE version strings into variables
* Replace literal usages of EE version numbers with custom attribute
* Use convention 'eeN' instead of 'eex' in filenames
* Update metadata tag for deploy module documentation
* Update deploy module documentation to discuss EE platform-specific deploy modules
* Add documentation for the resources module
* Add resources module into section table of contents
* Use jetty-home instead of JETTY_HOME as documentation attribute

Co-authored-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Greg Poulos 2023-01-19 13:02:42 -05:00 committed by GitHub
parent fc762aea7d
commit 06efbcaa7c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
22 changed files with 179 additions and 92 deletions

View File

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

View File

@ -46,46 +46,47 @@ 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} application; for other versions of Jakarta EE, make sure to activate the corresponding `{ee-all}-deploy` module.
[subs=attributes]
----
$ 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.
====
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 +97,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

View File

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

View File

@ -36,10 +36,11 @@ 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:
[subs=attributes]
----
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:

View File

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

View File

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

View File

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

View File

@ -1,33 +0,0 @@
//
// ========================================================================
// 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-deploy]]
===== Module `deploy`
The `deploy` module provides the deployment feature through a `DeploymentManager` component that watches a directory for changes (see xref:og-deploy[how to deploy web applications] for more information).
Files or directories added in this monitored directory cause the `DeploymentManager` to deploy them as web applications; updating files already existing in this monitored directory cause the `DeploymentManager` to re-deploy the correspondent web application; removing files in this monitored directory cause the `DeploymentManager` to undeploy the correspondent web application (see also xref:og-deploy-rules[here] for more information).
The module file is `$JETTY_HOME/modules/deploy.mod`:
----
include::{jetty-home}/modules/deploy.mod[]
----
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).

View File

@ -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 Jakarta EE platform's version of the Java Servlet specification.
Jetty's configuration properties are nearly identical across these versions; the configuration properties for the `{ee-current}-deploy` Jetty module are:
----
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).

View File

@ -0,0 +1,24 @@
//
// ========================================================================
// 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]
Multiple versions of this module exist (`{ee-all}-webapp`) to support each Jakarta EE platform's version of the Java Servlet specification.
Jetty's configuration properties are identical across all versions of this module, and are as follows:
----
include::{jetty-home}/modules/{ee-current}-webapp.mod[tags=ini-template]
----

View File

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

View File

@ -0,0 +1,22 @@
//
// ========================================================================
// 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-resources]]
===== Module `resources`
include::{jetty-home}/modules/resources.mod[tags=description]
A common use-case for this module is to provide resources for third-party libraries via the xref:og-start-start-class-path[server classpath].
For instance, many logging libraries (including https://logging.apache.org/log4j/2.x/[Log4j2] and https://logback.qos.ch/[Logback]) look for their configuration files on the classpath.
Jetty provides a logging library implementation -- enabled via the `logging-jetty` module -- whose configuration file is `$JETTY_BASE/resources/jetty-logging.properties`.

View File

@ -17,19 +17,22 @@
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-resources.adoc[]
include::module-server.adoc[]
include::module-ssl.adoc[]
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[]

View File

@ -79,7 +79,7 @@ startJVM --> forkedJVM: " waits for"
It is worth mentioning that there are two standard Jetty modules that allow you to easily add entries to the Jetty server class-path:
* The `resources` module, that adds the `$JETTY_BASE/resources/` directory to the server class-path.
* The xref:og-module-resources[`resources` module], which adds the `$JETTY_BASE/resources` directory to the server class-path.
This is useful if you have third party libraries that lookup resources from the class-path: just put those resources in the `$JETTY_BASE/resources/` directory. +
Logging libraries often perform class-path lookup of their configuration files (for example, `log4j.properties`, `log4j.xml`, `logging.properties`, and `logback.xml`), so `$JETTY_BASE/resources/` is the ideal place to add those files. +
* The the `ext` module, that adds all the `+*.jar+` files under the `$JETTY_BASE/lib/ext/` directory, and subdirectories recursively, to the server class-path. +

View File

@ -1,5 +1,5 @@
[description]
Enables web application deployment from the $JETTY_BASE/webapps/ directory.
This module enables web application deployment from the `$JETTY_BASE/webapps` directory.
[depend]
server
@ -7,6 +7,9 @@ server
[lib]
lib/jetty-deploy-${jetty.version}.jar
[files]
webapps/
[xml]
etc/jetty-deploy.xml

View File

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

View File

@ -1,8 +1,9 @@
# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
[description]
Adds the $JETTY_BASE/resources directory to the server classpath.
Useful for configuration property files (eg jetty-logging.properties)
# tag::description[]
This module adds the `$JETTY_BASE/resources` directory to the server's classpath.
# end::description[]
[tags]
classpath

View File

@ -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
@ -8,15 +10,11 @@ ee10
deploy
ee10-webapp
[lib]
[files]
webapps/
[xml]
etc/jetty-ee10-deploy.xml
[ini-template]
# tag::ini-template[]
## Monitored directory name (relative to $jetty.base)
# jetty.deploy.monitoredDir=webapps
## - OR -
@ -49,3 +47,4 @@ etc/jetty-ee10-deploy.xml
## Order of discovered ServletContainerInitializers
# jetty.deploy.servletContainerInitializerOrder=
# end::ini-template[]

View File

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

View File

@ -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]
ee8
@ -8,15 +10,11 @@ ee8
deploy
ee8-webapp
[lib]
[files]
webapps/
[xml]
etc/jetty-ee8-deploy.xml
[ini-template]
# tag::ini-template[]
## Monitored directory name (relative to $jetty.base)
# jetty.deploy.monitoredDir=webapps
## - OR -
@ -49,3 +47,4 @@ etc/jetty-ee8-deploy.xml
## Order of discovered ServletContainerInitializers
# jetty.deploy.servletContainerInitializerOrder=
# end::ini-template[]

View File

@ -17,7 +17,6 @@ etc/jetty-ee8-webapp.xml
[lib]
lib/jetty-ee8-webapp-${jetty.version}.jar
[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.

View File

@ -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]
ee9
@ -8,15 +10,11 @@ ee9
deploy
ee9-webapp
[lib]
[files]
webapps/
[xml]
etc/jetty-ee9-deploy.xml
[ini-template]
# tag::ini-template[]
## Monitored directory name (relative to $jetty.base)
# jetty.deploy.monitoredDir=webapps
## - OR -
@ -49,3 +47,4 @@ etc/jetty-ee9-deploy.xml
## Order of discovered ServletContainerInitializers
# jetty.deploy.servletContainerInitializerOrder=
# end::ini-template[]