Updated deploy documentation.

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>

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

@@ -2,7 +2,7 @@
 // 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
+:ee-current-caps: EE 10
 :experimental:
 :imagesdir: images
 :jetty-home: ../../../../../../../jetty-home/target/jetty-home

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

@@ -18,9 +18,17 @@ You can deploy two types of web application resources with Jetty:
 
 * *Standard Web Application Archives*, in the form of `+*.war+` files or web application directories, defined by the link:https://www.oracle.com/java/technologies/java-servlet-tec.html[Servlet specification].
 Their deployment is described in xref:og-begin-deploy-war[this section].
-* *Jetty context XML files*, that allow you to customize the deployment of standard web applications, and also allow you use Jetty components -- and possibly custom components written by you -- to assemble your web applications.
+* *Jetty context XML files*, that allow you to customize the deployment of standard web applications, and also allow you to use Jetty components -- and possibly custom components written by you -- to assemble your web applications.
 Their deployment is described in xref:og-deploy[this section].
 
+Jetty supports the deployment of both standard web applications and Jetty context XML files in a specific _environment_.
+
+In the following sections you can find simple examples of deployments of Jakarta {ee-current-caps} web applications.
+
+However, Jetty supports simultaneous deployment of web applications each to a possibly different environment, for example an old Java EE 8 web application alongside a new Jakarta {ee-current-caps} web application.
+
+Refer to the section about xref:og-deploy[deployment] for further information about how to deploy to different environments.
+
 [[og-begin-deploy-war]]
 ===== Deploying +*.war+ Files
 
@@ -48,7 +56,12 @@ mywebapp.war
 
 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.
+[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.
+
+Refer to the section about xref:og-deploy[deployment] for further information about how to deploy to different environments.
+====
 
 [subs=attributes]
 ----

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

@@ -14,12 +14,31 @@
 [[og-deploy]]
 === Web Application Deployment
 
-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.
+Most of the time 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-eeN-deploy[`{ee-all}-deploy` module] by processing xref:og-deploy-jetty[Jetty context XML files].
+Jetty supports the deployment of each web application to a specific _environment_.
+The available environments are:
+
+* Java EE 8 -- Supports Servlet 4.0 (and associated specifications) in the `+javax.*+` packages.
+* Jakarta EE 9 -- Supports Servlet 5.0 (and associated specifications) in the `+jakarta.*+` packages.
+* Jakarta EE 10 -- Supports Servlet 6.0 (and associated specifications) in the `+jakarta.*+` packages.
+* Jetty core -- Supports web applications written against the Jetty `Handler` APIs, without any Servlet dependencies.
+
+This means that you can simultaneously deploy an old Java EE 8 web application, say `old-ee8.war`, alongside a new Jakarta {ee-current-caps} web application, say `new-{ee-current}.war`, alongside a web application that only uses the Jetty `Handler` APIs, say `app-jetty.xml`.
+
+The customization is performed 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].
 
+For each specific environment there is a specific deploy module that you must enable:
+
+* For Java EE 8, xref:og-module-eeN-deploy[`ee8-deploy`]
+* For Java EE 9, xref:og-module-eeN-deploy[`ee9-deploy`]
+* For Java {ee-current-caps}, xref:og-module-eeN-deploy[`{ee-current}-deploy`]
+* For Jetty core, xref:og-module-core-deploy[`core-deploy`]
+
+Each of these modules provide the environment specific features, and depend on the `deploy` module that provides the scanning features.
+
 include::deploy-hot-static.adoc[]
 include::deploy-rules.adoc[]
 include::deploy-jetty.adoc[]

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

@@ -21,12 +21,12 @@ The web application resources are served by Jetty from the files extracted in th
 If you do not want Jetty to extract the `+*.war+` files, you can disable this feature, for example:
 
 .mywebapp.xml
-[source,xml,highlight=8]
+[source,xml,highlight=8,subs="verbatim,attributes"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
 
-<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
+<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
   <Set name="contextPath">/mywebapp</Set>
   <Set name="war">/opt/webapps/mywebapp.war</Set>
   <Set name="extractWAR">false</Set>

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

@@ -23,17 +23,17 @@ To deploy a web application using a Jetty context XML file, simply place the fil
 A simple Jetty context XML file, for example named `wiki.xml` is the following:
 
 .wiki.xml
-[source,xml,subs=verbatim]
+[source,xml,subs="verbatim,attributes"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
 
-<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext"> <1>
+<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext"> <1>
   <Set name="contextPath">/wiki</Set> <2>
   <Set name="war">/opt/myapps/myapp.war</Set> <3>
 </Configure>
 ----
-<1> Configures a link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
+<1> Configures a link:{javadoc-url}/org/eclipse/jetty/{ee-current}/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
 <2> Specifies the web application `contextPath`, which may be different from the `+*.war+` file name.
 <3> Specifies the file system path of the `+*.war+` file.
 
@@ -57,12 +57,12 @@ IMPORTANT: If you place both the Jetty context XML file _and_ the `+*.war+` file
 You can use the features of xref:og-xml[Jetty XML files] to avoid to hard-code file system paths or other configurations in your Jetty context XML files, for example by using system properties:
 
 .wiki.xml
-[source,xml]
+[source,xml,subs="verbatim,attributes"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
 
-<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
+<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
   <Set name="contextPath">/wiki</Set>
   <Set name="war"><SystemProperty name="myapps.dir"/>/myapp.war</Set>
 </Configure>

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

@@ -18,12 +18,12 @@ A web application may _reference_ a JNDI entry, such as a JDBC `DataSource` from
 The JNDI entry must be _defined_ in a xref:og-jndi-xml[Jetty XML file], for example a context XML like so:
 
 .mywebapp.xml
-[source,xml,subs=normal]
+[source,xml,subs="verbatim,attributes"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
 
-<Configure id="wac" class="org.eclipse.jetty.ee9.webapp.WebAppContext">
+<Configure id="wac" class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
   <Set name="contextPath">/mywebapp</Set>
   <Set name="war">/opt/webapps/mywebapp.war</Set>
 #&nbsp;&nbsp;<New class="org.eclipse.jetty.plus.jndi.Resource">
@@ -47,8 +47,8 @@ For more information and examples on how to use JNDI in Jetty, refer to the xref
 Class `com.mysql.cj.jdbc.MysqlConnectionPoolDataSource` is present in the MySQL JDBC driver file, `mysql-connector-java-<version>.jar`, which must be available on the server's classpath .
 
 If the class is instead present _within_ the web application, then the JNDI entry must be declared in a `WEB-INF/jetty-env.xml` file - see the xref:og-jndi[JNDI] feature section for more information and examples.
-
 ====
+
 // TODO: add a link to reference the section about how
 //  to add a JDBC driver jar to the server classpath.
 

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

@@ -19,12 +19,12 @@ This additional `web.xml` is processed _after_ the `+*.war+` file `web.xml`.
 This allows you to add host specific configuration or server specific configuration without having to extract the web application `web.xml`, modify it, and repackage it in the `+*.war+` file.
 
 .mywebapp.xml
-[source,xml,highlight=8]
+[source,xml,highlight=8,subs="verbatim,attributes"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
 
-<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
+<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
   <Set name="contextPath">/mywebapp</Set>
   <Set name="war">/opt/webapps/mywebapp.war</Set>
   <Set name="overrideDescriptor">/opt/webapps/mywebapp-web.xml</Set>
@@ -39,8 +39,8 @@ The format of the additional `web.xml` is exactly the same as a standard `web.xm
 <?xml version="1.0" encoding="UTF-8"?>
 <web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
+         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
-         version="4.0">
+         version="6.0">
   <servlet>
     <servlet-name>my-servlet</servlet-name>
     <init-param>

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

@@ -20,19 +20,44 @@ _Updating_ a `+*.war+` file or a Jetty context XML file causes the `DeploymentMa
 
 _Removing_ a `+*.war+` file, a `+*.war+` directory, a Jetty context XML file or a normal directory from `$JETTY_BASE/webapps` causes the `DeploymentManager` to undeploy the web application, which means that the Jetty context component representing the web application is stopped and removed from the Jetty server.
 
+[[og-deploy-rules-context-path]]
+===== Context Path Resolution
+
 When a file or directory is added to `$JETTY_BASE/webapps`, the `DeploymentManager` derives the web application `contextPath` from the file or directory name, with the following rules:
 
 * If the directory name is, for example, `mywebapp/`, it is deployed as a standard web application if it contains a `WEB-INF/` subdirectory, otherwise it is deployed as a web application of static content.
 The `contextPath` would be `/mywebapp` (that is, the web application is reachable at `+http://localhost:8080/mywebapp/+`).
-* If the directory name is `ROOT`, case insensitive, the `contextPath` is `/` (that is, the web application is reachable at `+http://localhost:8080/+`).
+* If the directory name is `ROOT`, case-insensitive, the `contextPath` is `/` (that is, the web application is reachable at `+http://localhost:8080/+`).
 * If the directory name ends with `.d`, for example `config.d/`, it is ignored, although it may be referenced to configure other web applications (for example to store common files).
 * If the `+*.war+` file name is, for example, `mywebapp.war`, it is deployed as a standard web application with the context path `/mywebapp` (that is, the web application is reachable at `+http://localhost:8080/mywebapp/+`).
-* If the file name is `ROOT.war`, case insensitive, the `contextPath` is `/` (that is, the web application is reachable at `+http://localhost:8080/+`).
+* If the file name is `ROOT.war`, case-insensitive, the `contextPath` is `/` (that is, the web application is reachable at `+http://localhost:8080/+`).
 * If both the `mywebapp.war` file and the `mywebapp/` directory exist, only the file is deployed.
 This allows the directory with the same name to be the `+*.war+` file unpack location and avoid that the web application is deployed twice.
-* A xref:og-deploy-jetty[Jetty context XML file] named `mywebapp.xml` is deployed as a web application by processing the directives contained in the XML file itself, which must set the `contextPath`.
+* A xref:og-deploy-jetty[Jetty context XML file] named `mywebapp.xml` is deployed as a web application by processing the directives contained in the XML file itself, which must set the `contextPath`, which could be different from the name of the XML file.
 * If both `mywebapp.xml` and `mywebapp.war` exist, only the XML file is deployed.
 This allows the XML file to reference the `+*.war+` file and avoid that the web application is deployed twice.
 
+[[og-deploy-rules-environment]]
+===== Environment Resolution
+
+A web application is always deployed to a specific environment.
+
+If you enabled only one specific deployer module, for example `{ee-current}-deploy`, then the web applications and the Jetty context XML files in `$JETTY_BASE/webapps` will be deployed to the `{ee-current}` environment.
+
+You can enable multiple deployer modules if you need to deploy multiple web applications each to a specific environment.
+
+For example, you have an `old-ee9.war` web application that you want to deploy to the Jakarta EE 9 environment, and a `new-{ee-current}.war` web application that you want to deploy to the Jakarta {ee-current-caps} environment.
+First, you must enable both the `ee9-deploy` and the `{ee-current}-deploy` modules.
+Then, you add a `+*.properties+` file with the same name of the web application, in the example above `$JETTY_BASE/webapps/old-ee9.properties`, with the following content:
+
+[source,properties]
+====
+environment=ee9
+====
+
+You may also add a `+*.properties+` file for `new-{ee-current}.war`, but it is not necessary because the most recent environment is used by default.
+// TODO: verify the statement above. For an ee8 and an ee9 webapp, is it true that ee9 will be used by default (or ee10 will)?
+
+
 // TODO: add section about the work directory from
 //  old_docs/contexts/temporary-directories.adoc

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

@@ -53,12 +53,12 @@ For example if the non-ASCII domain name `www.√integral.com` is given to a bro
 
 If you have a web application `mywebapp.war` you can configure its virtual hosts in this way:
 
-[source,xml]
+[source,xml,subs="verbatim,attributes"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
 
-<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
+<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
   <Set name="contextPath">/mywebapp</Set>
   <Set name="war">/opt/webapps/mywebapp.war</Set>
   <Set name="virtualHosts">
@@ -98,12 +98,12 @@ You have `domain.war` that you want to deploy at `+http://domain.biz/+` and `hob
 To achieve this, you simply use the same context path of `/` for each of your webapps, while specifying different virtual hosts for each of your webapps:
 
 .domain.xml
-[source,xml]
+[source,xml,subs="verbatim,attributes"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
 
-<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
+<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
   <Set name="contextPath">/</Set>
   <Set name="war">/opt/webapps/domain.war</Set>
   <Set name="virtualHosts">
@@ -115,12 +115,12 @@ To achieve this, you simply use the same context path of `/` for each of your we
 ----
 
 .hobby.xml
-[source,xml]
+[source,xml,subs="verbatim,attributes"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
 
-<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
+<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
   <Set name="contextPath">/</Set>
   <Set name="war">/opt/webapps/hobby.war</Set>
   <Set name="virtualHosts">
@@ -143,12 +143,12 @@ This configuration may be useful when Jetty sits behind a load balancer.
 In this case, you want to xref:og-protocols[configure multiple connectors], each with a different name, and then reference the connector name in the web application virtual host configuration:
 
 .domain.xml
-[source,xml,highlight=10]
+[source,xml,highlight=10,subs="verbatim,attributes"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
 
-<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
+<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
   <Set name="contextPath">/</Set>
   <Set name="war">/opt/webapps/domain.war</Set>
   <Set name="virtualHosts">
@@ -160,12 +160,12 @@ In this case, you want to xref:og-protocols[configure multiple connectors], each
 ----
 
 .hobby.xml
-[source,xml,highlight=10]
+[source,xml,highlight=10,subs="verbatim,attributes"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
 
-<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
+<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
   <Set name="contextPath">/</Set>
   <Set name="war">/opt/webapps/hobby.war</Set>
   <Set name="virtualHosts">

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

@@ -0,0 +1,23 @@
+//
+// ========================================================================
+// Copyright (c) 1995 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-core-deploy]]
+===== Module `core-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.
+
+TODO
+// TODO see module-eeN-deploy.adoc

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

@@ -17,6 +17,7 @@
 include::module-alpn.adoc[]
 include::module-bytebufferpool.adoc[]
 include::module-console-capture.adoc[]
+include::module-core-deploy.adoc[]
 include::module-eeN-deploy.adoc[]
 include::module-http.adoc[]
 include::module-http2.adoc[]