Update deployment documentation for new features (#11997)

documentation/jetty/modules/operations-guide/pages/deploy/index.adoc

@@ -199,6 +199,56 @@ Note how the `+*.war+` file path is now obtained by resolving the system propert
 $ java -jar $JETTY_HOME/start.jar -Dmyapps.dir=/opt/myapps
 ----
 
+[[jetty]]
+== Deploying Environment Specific Context XML Files
+
+A xref:xml/index.adoc[Jetty context XML file] file can be applied to _all_ webapps deployed to a particular `environment` by adding a file named `{ee-all}.properties` containing the location of the file.
+
+This environment-specific Jetty context XML file will be applied to the webapps _before_ any context XML file associated with the webapp.
+Thus, it can be used to configure general defaults to all webapps for a given `environment`, allowing a webapp-specific context XML file to further refine or override that configuration.
+
+IMPORTANT: The contents of the environment specific context XML file may only contain references to classes appropriate for that environment.
+
+The `{ee-all}.properties` file must be in the same directory as the webapp being deployed.
+It must contain the property `jetty.deploy.environmentXml` set to the location of the context XML file.
+The location may be either absolute or relative to the parent of the deployment directory (usually `$JETTY_BASE`).
+
+For example, given the previous example of a `$JETTY_BASE/webapps/wiki.xml` and its accompanying `$JETTY_BASE/webapps/wiki.properties` file that declares the `wiki` webapp should be deployed to environment `{ee-current}`, a file called `$JETTY_BASE/webapps/{ee-current}.properties` can be defined containing the following:
+
+.{ee-current}.properties
+[,properties,subs=attributes+]
+----
+jetty.deploy.environmentXml=etc/{ee-current}-context.xml
+----
+
+The directory structure would look like this:
+
+.directory structure
+[,properties,subs=attributes+]
+----
+$JETTY_BASE
+├── etc
+│   └── {ee-current}-context.xml
+└── webapps
+    ├── {ee-current}.properties
+    ├── wiki.properties
+    └── wiki.xml
+----
+
+The contents of the `$JETTY_BASE/etc/{ee-current}-context.xml` file will be applied to the `wiki` webapp instance _before_ the `wiki.xml`, allowing the contents of the latter to override the contents of the former.
+
+== WEB-INF/jetty-{ee-all}-web.xml
+
+As discussed above, a Jetty context XML file can be used to configure a webapp during deployment.
+The webapp can also be configured during its startup phase by a `WEB-INF/jetty-{ee-all}-web.xml` file.
+The contents of this file is the same as a Jetty context XML file.
+This file can be useful:
+
+* to place all configuration inside your webapp archive
+* to perform configuration that can only occur _after_ the webapp's classpath has been created
+
+TIP: it is good practice to name the file according to the `environment` into which the webapp will be deployed. If your webapp can be deployed to multiple `environments` then you should include a `WEB-INF` file for each one. If you only deploy to a single `environment` then you can omit it from the filename, however be aware that you cannot change environments without updating the contents of the file.
+
 [[jndi]]
 == Configuring JNDI Entries
 
@@ -234,7 +284,7 @@ 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:jndi/index.adoc[JNDI] feature section for more information and examples.
+If the class is instead present _within_ the web application, then the JNDI entry must be declared in a `WEB-INF/jetty-{ee-all}-env.xml` file - which is applied after the webapp's classpath has been set up - see the xref:jndi/index.adoc[JNDI] feature section for more information and examples.
 ====
 
 [[virtual-hosts]]

documentation/jetty/modules/operations-guide/pages/jndi/index.adoc

@@ -33,7 +33,10 @@ You must declare the objects you want bound so that you can then hook them into
 
 You make these declarations in Jetty XML files that are either _external_  or _internal_ to your webapp.
 A server or context XML file is external to your webapp.
-The special `WEB-INF/jetty-env.xml` file is internal to your webapp.
+The special `WEB-INF/jetty-{ee-all}-env.xml` file is internal to your webapp. 
+
+TIP: It is good practice to name the file according to the `environment` into which your webapp is deployed. This way you can supply a file for each `environment` into which you deploy the webapp . If you only ever deploy to a single environment, you may omit the `environment` from the name, however be aware that you cannot change environments without updating the contents of the file to match.
+
 See the section on <<xml,Jetty XML files>> for more information on how to choose in which XML file to place your declarations.
 
 Regardless of its location, the XML file contains declarations of JNDI resources that can be referenced later within your webapp.
@@ -291,7 +294,7 @@ This ensures that the two are linked together and thus accessible to your webapp
 However, if the names cannot be the same, then it is possible to effectively alias one to another using an `org.eclipse.jetty.plus.jndi.Link`.
 
 Supposing you have a declaration for a Datasource named `jdbc/workforce` in a Jetty context XML file, but your web.xml wants to link to a `<resource-ref>` named `jdbc/employees`, and you cannot edit the web.xml.
-You can create a `WEB-INF/jetty-env.xml` file with an `org.eclipse.jetty.plus.jndi.Link` that ties together the names `jdbc/workforce` and `jdbc/employees`:
+You can create a `WEB-INF/jetty-{ee-all}-env.xml` file with an `org.eclipse.jetty.plus.jndi.Link` that ties together the names `jdbc/workforce` and `jdbc/employees`:
 
 The context XML file declares `jdbc/workforce`:
 
@@ -324,7 +327,7 @@ The `web.xml` refers to it as `jdbc/employees`:
 </resource-ref>
 ----
 
-Create a `WEB-INF/jetty-env.xml` file with a `org.eclipse.jetty.plus.jndi.Link` to link these names together:
+Create a `WEB-INF/jetty-{ee-all}-env.xml` file with a `org.eclipse.jetty.plus.jndi.Link` to link these names together:
 
 .wiki.xml
 [,xml,subs=attributes+]
@@ -352,8 +355,8 @@ Context XML file::
 Entries in a context XML file should be <<scope,scoped>> at the level of the webapp to which they apply (it is possible to use a less strict scoping level of Server or JVM, but not recommended).
 As a context XML file executes _before_ the webapp's classes are available, the classes for your resource must be external to the webapp and on either the container or environment classpath.
 
-WEB-INF/jetty-env.xml::
-Naming resources in a `WEB-INF/jetty-env.xml` file are <<scope,scoped>> to the webapp in which the file resides.
+WEB-INF/jetty-{ee-all}-env.xml::
+Naming resources in a `WEB-INF/jetty-{ee-all}-env.xml` file are <<scope,scoped>> to the webapp in which the file resides.
 The resources defined here may use classes from inside your webapp.
 
 [[scope]]

jetty-ee10/jetty-ee10-webapp/src/main/java/org/eclipse/jetty/ee10/webapp/JettyWebXmlConfiguration.java

@@ -86,7 +86,7 @@ public class JettyWebXmlConfiguration extends AbstractConfiguration
     }
 
     /**
-     * Obtain a WEB-INF/jetty-ee9-web.xml, falling back to
+     * Obtain a WEB-INF/jetty-ee10-web.xml, falling back to
      * looking for WEB-INF/jetty-web.xml.
      *
      * @param webInf the WEB-INF of the context to search