diff --git a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-web-xml-config.adoc b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-web-xml-config.adoc
index 154518ab115..4d42bfb6b49 100644
--- a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-web-xml-config.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-web-xml-config.adoc
@@ -30,15 +30,12 @@ For a more in-depth look at the syntax, see xref:jetty-xml-syntax[].
[source, xml, subs="{sub-order}"]
----
-
..
-
-
----
____
diff --git a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-syntax.adoc b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-syntax.adoc
index 6915889615a..cae32fe2abb 100644
--- a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-syntax.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-syntax.adoc
@@ -53,7 +53,7 @@ The following XML configuration file creates some Java objects and sets some att
demo2
-
+
----
The XML above is equivalent to the following Java code:
@@ -72,7 +72,7 @@ bar.init(false);
foo.setNested(bar);
bar.setWibble(20);
-bar.getParent().setName("demo2");
+bar.getParent().setName("demo2");
----
==== Overview
@@ -80,41 +80,27 @@ bar.getParent().setName("demo2");
===== Understanding DTD and Parsing
The document type descriptor
-(link:{GITBROWSEURL}/jetty-xml/src/main/resources/org/eclipse/jetty/xml/configure_9_0.dtd?h=release-9[configure.dtd])
-describes all valid elements in a Jetty XML configuration file using the
-Jetty IoC format. The first two lines of an XML must reference the DTD
-to be used to validate the XML like:
+(link:{GITBROWSEURL}/jetty-xml/src/main/resources/org/eclipse/jetty/xml/configure_9_0.dtd?h=release-9[configure.dtd]) describes all valid elements in a Jetty XML configuration file using the Jetty IoC format.
+The first two lines of an XML must reference the DTD to be used to validate the XML like:
[source, xml, subs="{sub-order}"]
----
-
...
-
-
----
-Typcically a good XML editor will fetch the DTD from the URL and use it
-to give syntax highlighting and validation while a configuration file is
-being edited. Some editors also allows DTD files to be locally cached.
-The URL may point to configure.dtd if you want the latest current
-version, or to a specific version like configure_9_0.dtd if you want a
-particular validation feature set.
+Typcically a good XML editor will fetch the DTD from the URL and use it to give syntax highlighting and validation while a configuration file is being edited.
+Some editors also allows DTD files to be locally cached.
+The URL may point to configure.dtd if you want the latest current version, or to a specific version like configure_9_0.dtd if you want a particular validation feature set.
-Files that conform to the configure.dtd format are processed in Jetty by
-the `XmlConfiguration` class which may also validate the XML (using a
-version of the DTD from the classes jar file), but is by default run in
-a forgiving mode that tries to work around validation failures.
+Files that conform to the configure.dtd format are processed in Jetty by the `XmlConfiguration` class which may also validate the XML (using a version of the DTD from the classes jar file), but is by default run in a forgiving mode that tries to work around validation failures.
===== Jetty XML Configuration Scope
-The configuration of object instances with Jetty IoC XML is done on a
-scoped basis, so that for any given XML element there is a corresponding
-Object in scope and the nested XML elements apply to that. The outer
-most scope is given by a Configure element and elements like Call, New
-and Get establish new scopes. The following example uses the name fields
-to explain the scope
+The configuration of object instances with Jetty IoC XML is done on a scoped basis, so that for any given XML element there is a corresponding Object in scope and the nested XML elements apply to that.
+The outer most scope is given by a Configure element and elements like Call, New and Get establish new scopes.
+The following example uses the name fields to explain the scope.
[source, xml, subs="{sub-order}"]
----
@@ -134,50 +120,36 @@ to explain the scope
-
----
===== Coercing Arguments to a Type
-When trying to match XML elements to java elements, Jetty
-XmlConfiguration may need to coerces values to match method arguments.
-By default it does so on a best effort basis, but you can also specify
-explicit types with the `type` attribute. Supported values for type are:
-String, Character, Short, Byte, Integer, Long, Boolean, Float, Double,
-char, short, byte, int, long, boolean, float, double, URL, InetAddress,
-InetAddrPort, void
+When trying to match XML elements to java elements, Jetty `XmlConfiguration` may need to coerces values to match method arguments.
+By default it does so on a best effort basis, but you can also specify explicit types with the `type` attribute.
+Supported values for type are: `String`, `Character`, `Short`, `Byte`, `Integer`, `Long`, `Boolean`, `Float`, `Double`, `char`, `short`, `byte`, `int`, `long`, `boolean`, `float`, `double`, `URL`, `InetAddress`, `InetAddrPort`, and `void`.
===== Referring to a Class
-If you do not specify the classname, Jetty assumes you are calling the
-method on the object that is current in scope (eg the object of the
-surrounding Configure, New or Get clause). If the class attribute is
-specified to a fully-qualified class name, then it is either used to
-create a new instance (Configure and New elements) or is used to access
-a static (Call, Set or Get elements).
+If you do not specify the classname, Jetty assumes you are calling the method on the object that is current in scope (eg the object of the surrounding `Configure`, `New` or `Get` clause).
+If the class attribute is specified to a fully-qualified class name, then it is either used to create a new instance (`Configure` and `New` elements) or is used to access a static (`Call`, `Set` or `Get` elements).
===== Referring to an Object
-You can use the id attribute to store a reference to the current object
-when first creating or referring to this object. You can then use the
-link:#jetty-xml-ref[Ref element] to reference the object later. The id
-must be unique for each object you create.
+You can use the id attribute to store a reference to the current object when first creating or referring to this object.
+You can then use the link:#jetty-xml-ref[Ref element] to reference the object later.
+The ID must be unique for each object you create.
===== Attribute vs Element Style
-For XML elements that contain only other XML Elements, there is a choice
-of using attributes or elements style. The following is an example of
-attribute style:
+For XML elements that contain only other XML Elements, there is a choice of using attributes or elements style.
+The following is an example of attribute style:
....
....
-Attribute style has the benefit of brevity, but is limited by: values
-can only be Strings; multivalued items can not contain ','; values may
-not be subject to property expansion or other elements that return
-values. Thus the more verbose element style is available and the
-following is semantically equivalent to the attribute style above:
+Attribute style has the benefit of brevity, but is limited by: values can only be Strings; multivalued items can not contain ','; values may not be subject to property expansion or other elements that return values.
+Thus, the more verbose element style is available and the following is semantically equivalent to the attribute style above:
....
@@ -189,11 +161,8 @@ following is semantically equivalent to the attribute style above:
....
-Note that multivalued elements like Arg, must be repeated and may not be
-comma separated like they are when provided as attributes. It is
-possible to use a mix of styles and the following example shows a more
-typical example that uses property expansion as the reason for element
-style:
+Note that multivalued elements like `Arg` must be repeated and may not be comma-separated like they are when provided as attributes.
+It is possible to use a mix of styles and the following example shows a moretypical example that uses property expansion as the reason for element style:
....
@@ -205,16 +174,14 @@ style:
....
-Attributes may not be expressed as elements when their parent element is
-one that contains data. Thus Arg, Item, Set, Put and Get elements may
-not have their attributes expressed as elements.
+Attributes may not be expressed as elements when their parent element is one that contains data.
+Thus `Arg`, `Item`, `Set`, `Put` and `Get` elements may not have their attributes expressed as elements.
[[jetty-xml-configure]]
====
-This is the root element that specifies the class of object that is to
-be configured. It is usually either the Server, in `jetty.xml`, or a
-WebAppContext in `jetty-web.xml`.
+This is the root element that specifies the class of object that is to be configured.
+It is usually either the Server, in `jetty.xml`, or a `WebAppContext` in `jetty-web.xml`.
[cols=",,",options="header",]
|=======================================================================
@@ -226,8 +193,8 @@ You can use this to break up configuration of an object (such as the
Server) across multiple files.
|class |no |The fully qualified classname of the object to be
-configured. Could be org.eclipse.jetty.server.Server,
-org.eclipse.jetty.webapp.WebAppContext, a handler, etc.
+configured. Could be `org.eclipse.jetty.server.Server`,
+`org.eclipse.jetty.webapp.WebAppContext`, a handler, etc.
|=======================================================================
===== Can Contain
@@ -246,7 +213,7 @@ link:#jetty-xml-property[Property element]
----
8080
-
+
----
This is equivalent to:
@@ -254,46 +221,43 @@ This is equivalent to:
[source, java, subs="{sub-order}"]
----
org.eclipse.jetty.server.Server server = new org.eclipse.jetty.server.Server();
-server.setPort(8080);
+server.setPort(8080);
----
-====== Using id to break up configuration of one object across multiple
-files
+====== Using id to break up configuration of one object across multiple files
-(etc/jetty.xml)
+In `etc/jetty.xml`:
[source, xml, subs="{sub-order}"]
----
-
+
----
-(etc/jetty-logging.xml)
+In `etc/jetty-logging.xml`:
[source, xml, subs="{sub-order}"]
----
-
+
----
Then run the combined configuration using:
....
-java -jar start.jar etc/jetty.xml jetty-logging.xml
+java -jar start.jar etc/jetty.xml jetty-logging.xml
....
[[jetty-xml-set]]
====
-A Set element maps to a call to a setter method or field on the current
-object. It can contain text and/or elements such as Call, New,
-SystemProperty, etc., as values. The name and optional type attributes
-are used to select the setter method. If you do not specify a value
-type, white space is trimmed out of the value. If it contains multiple
-elements as values, they are added as strings before being converted to
-any specified type.
+A Set element maps to a call to a setter method or field on the current object.
+It can contain text and/or elements such as `Call`, `New`, `SystemProperty`, etc., as values.
+The name and optional type attributes are used to select the setter method.
+If you do not specify a value type, white space is trimmed out of the value.
+If it contains multiple elements as values, they are added as strings before being converted to any specified type.
[cols=",,",options="header",]
|=======================================================================
@@ -325,7 +289,7 @@ link:#jetty-xml-property[Property element]
----
8080
-
+
----
====== Set via a System Property
@@ -334,7 +298,7 @@ link:#jetty-xml-property[Property element]
----
-
+
----
====== Creating a NewObject and Setting It on the Server
@@ -348,7 +312,7 @@ link:#jetty-xml-property[Property element]
1000
-
+
----
This is equivalent to:
@@ -361,7 +325,7 @@ org.eclipse.jetty.util.thread.QueuedThreadPool threadPool = new org.eclipse.jett
threadPool.setMinThreads(10);
threadPool.setMaxThreads(1000);
-server.setThreadPool(threadPool);
+server.setThreadPool(threadPool);
----
====== Invoking a Static Setter
@@ -370,15 +334,14 @@ server.setThreadPool(threadPool);
----
loggerName
-
+
----
[[jetty-xml-get]]
====
-A Get element maps to a call to a getter method or field on the current
-object. It can contain nested elements such as Set, Put, Call, etc.;
-these act on the object returned by the Get call.
+A Get element maps to a call to a getter method or field on the current object.
+It can contain nested elements such as `Set`, `Put`, `Call`, etc.; these act on the object returned by the `Get` call.
[cols=",,",options="header",]
|=======================================================================
@@ -406,14 +369,14 @@ link:#jetty-xml-property[Property element]
====== Basic Example
-This simple example doesn't do much on its own. You would normally use
-this in conjunction with a [
-A Ref element allows a previously created object to be referenced by a
-unique id. It can contain a sequence of elements, such as Set or Put
-which then act on the referenced object. You can also use a Ref element
-as a value for other elements such as Set and Arg.
+A `Ref` element allows a previously created object to be referenced by a unique id.
+It can contain a sequence of elements, such as `Set` or `Put` which then act on the referenced object.
+You can also use a `Ref` element as a value for other elements such as `Set` and `Arg`.
-The Ref element provides convenience and eases readability. You can
-usually achieve the effect of the Ref by nesting elements (method
-calls), but this can get complicated very easily. The Ref element makes
-it possible to refer to the same object if you're using it multiple
-times, or passing it into multiple methods. It also makes it possible to
-split up configuration across multiple files.
+The `Ref` element provides convenience and eases readability.
+You can usually achieve the effect of the `Ref` by nesting elements (method calls), but this can get complicated very easily.
+The Ref element makes it possible to refer to the same object if you're using it multiple times, or passing it into multiple methods.
+It also makes it possible to split up configuration across multiple files.
[cols=",,",options="header",]
|=======================================================================
@@ -768,13 +719,12 @@ link:#jetty-xml-property[Property element]
====== Basic example
-Use the referenced object as an argument to a method call or
-constructor:
+Use the referenced object as an argument to a method call or constructor:
[source, xml, subs="{sub-order}"]
----
-][
1, 2, 3
-]
+
----
This is equivalent to:
@@ -800,13 +750,13 @@ This is equivalent to:
[source, java, subs="{sub-order}"]
----
foo = getXFoo();
-foo.setTest("1, 2, 3");
+foo.setTest("1, 2, 3");
----
====== Ref vs. Nested Elements
-Here is an example of the difference in syntax between using the Ref
-element, and nesting method calls. They are exactly equivalent:
+Here is an example of the difference in syntax between using the `Ref` element, and nesting method calls.
+They are exactly equivalent:
[source, xml, subs="{sub-order}"]
----
@@ -822,11 +772,10 @@ element, and nesting method calls. They are exactly equivalent:
true
-
+
----
-Here is a more practical example, taken from the handler configuration
-section in ` etc/jetty.xml`:
+Here is a more practical example, taken from the handler configuration section in `etc/jetty.xml`:
[source, xml, subs="{sub-order}"]
----
@@ -862,13 +811,13 @@ section in ` etc/jetty.xml`:
[
....
-]
+
----
[[jetty-xml-array]]
====
-An Array element allows the creation of a new array.
+An `Array` element allows the creation of a new array.
[cols=",,",options="header",]
|==================================================================
@@ -895,13 +844,13 @@ This is equivalent to:
[source, java, subs="{sub-order}"]
----
-String[] a = new String[] { "value0", new String("value1") };
+String[] a = new String[] { "value0", new String("value1") };
----
[[jetty-xml-item]]
==== -
-An Item element defines an entry for Array and Map elements.
+An `Item` element defines an entry for Array and Map elements.
[cols=",,",options="header",]
|=======================================================================
@@ -921,8 +870,7 @@ link:#jetty-xml-property[Property element]
[[jetty-xml-map]]
====
+
----
This is equivalent to:
@@ -951,14 +899,13 @@ This is equivalent to:
[source, java, subs="{sub-order}"]
----
Map m = new HashMap();
-m.put("keyName", new String("value1"));
+m.put("keyName", new String("value1"));
----
[[jetty-xml-entry]]
====
-An Entry element contains a key-value link:#jetty-xml-item[Item element]
-pair for a Map.
+An `Entry` element contains a key-value link:#jetty-xml-item[Item element] pair for a `Map`.
===== Can Contain
@@ -967,8 +914,8 @@ link:#jetty-xml-item[Item element]
[[jetty-xml-system-property]]
====
-A SystemProperty element gets the value of a JVM system property. It can
-be used within elements that accept values, such as Set, Put, Arg.
+A `SystemProperty` element gets the value of a JVM system property.
+It can be used within elements that accept values, such as `Set`, `Put`, `Arg`.
[cols=",,",options="header",]
|=======================================================================
@@ -983,31 +930,30 @@ later.
===== Can Contain
-Only attributes as Elements (Id, Name, Default).
+Only attributes as Elements (`Id`, `Name`, `Default`).
===== Example
[source, xml, subs="{sub-order}"]
----
-
+
----
That is equivalent to:
[source, java, subs="{sub-order}"]
----
-System.getProperty("jetty.http.port", "8080");
+System.getProperty("jetty.http.port", "8080");
----
-Both try to retrieve the value of jetty.http.port. If jetty.http.port is
-not set, then 8080 is used.
+Both try to retrieve the value of `jetty.http.port`.
+If `jetty.http.port` is not set, then 8080 is used.
[[jetty-xml-property]]
====
-A Property element allows arbitrary properties to be retrieved by name.
-It can contain a sequence of elements, such as Set, Put, Call that act
-on the retrieved object.
+A `Property` element allows arbitrary properties to be retrieved by name.
+It can contain a sequence of elements, such as `Set`, `Put`, `Call` that act on the retrieved object.
[cols=",,",options="header",]
|=======================================================================
@@ -1020,17 +966,13 @@ on the retrieved object.
later.
|=======================================================================
-The `name` attribute may be a comma separated list of property names,
-with the first property name being the "official" name, and the others
-names being old, deprecated property names that are kept for backward
-compatibility. A warning log is issued when deprecated property names
-are used. The `default` attribute contains the value to use in case none
-of the property names is found.
+The `Name` attribute may be a comma separated list of property names, with the first property name being the "official" name, and the others names being old, deprecated property names that are kept for backward compatibility.
+A warning log is issued when deprecated property names are used.
+The `Default` attribute contains the value to use in case none of the property names is found.
===== Can Contain
-The attributes may be expressed as contained Elements (Id, Name,
-Default).
+The attributes may be expressed as contained Elements (`Id`, `Name`, `Default`).
===== Example
@@ -1040,5 +982,5 @@ Default).
jdbcIdMgr
-
+
----
diff --git a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-usage.adoc b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-usage.adoc
index 43a4afb6186..c86edafe06e 100644
--- a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-usage.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-usage.adoc
@@ -18,7 +18,7 @@
=== Jetty XML Usage
Jetty provides an XML-based configuration.
-It is grounded in Java's Reflection API. Classes in the java.lang.reflect represent Java methods and classes, such that you can instantiate objects and invoke their methods based on their names and argument types.
+It is grounded in Java's Reflection API. Classes in the `java.lang.reflect` represent Java methods and classes, such that you can instantiate objects and invoke their methods based on their names and argument types.
Behind the scenes, Jetty's XML config parser translates the XML elements and attributes into Reflection calls.
[[using-jettyxml]]
@@ -28,7 +28,7 @@ To use `jetty.xml`, specify it as a configuration file when running Jetty.
[source, java, subs="{sub-order}"]
----
- java -jar start.jar etc/jetty.xml
+ java -jar start.jar etc/jetty.xml
----
____
@@ -48,24 +48,24 @@ If you use the same ID across multiple configuration files, those configurations
[[setting-parameters-in-configuration-files]]
==== Setting Parameters in Configuration Files
-You can set parameters in configuration files either with system properties (using ` `) or properties files (using ``) passed via the command line.
+You can set parameters in configuration files either with system properties (using ``) or properties files (using ``) passed via the command line.
For example, this code in `jetty.xml` allows the port to be defined on the command line, falling back onto `8080`if the port is not specified:
[source, xml, subs="{sub-order}"]
----
-
+
----
Then you modify the port while running Jetty by using this command:
[source, java, subs="{sub-order}"]
----
- java -Djetty.http.port=8888 -jar start.jar etc/jetty.xml
+ java -Djetty.http.port=8888 -jar start.jar etc/jetty.xml
----
An example of defining both system properties and properties files from the command line:
[source, java, subs="{sub-order}"]
----
- java -Djetty.http.port=8888 -jar start.jar myjetty.properties etc/jetty.xml etc/other.xml
+ java -Djetty.http.port=8888 -jar start.jar myjetty.properties etc/jetty.xml etc/other.xml
----
diff --git a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/override-web-xml.adoc b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/override-web-xml.adoc
index 0fb49fad62e..60f26ea37df 100644
--- a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/override-web-xml.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/override-web-xml.adoc
@@ -22,33 +22,31 @@ The challenge is to do so without changing the webapp itself. You can use a `jet
But there are some changes that `jetty.xml` cannot accomplish, for example, modifications to servlet init-params and context init-params.
Using `webdefault.xml` is not an option because Jetty applies `webdefault.xml` to a web application _before_ the application's own `WEB-INF/web.xml`, which means that it cannot override values inside the webapp's ` web.xml`.
-The solution is `override-web.xml`. It is a `web.xml` file that Jetty applies to a web application _after_ the application's own `WEB-INF/web.xml`, which means that it can override values or add new elements.
-You define it per-webapp, using the xref:jetty-xml-syntax[].
+The solution is `override-web.xml`.
+It is a `web.xml` file that Jetty applies to a web application _after_ the application's own `WEB-INF/web.xml`, which means that it can override values or add new elements.
+This is defined on a per-webapp basis, using the xref:jetty-xml-syntax[].
[[using-override-web-xml]]
-==== Using `override-web.xml`
+==== Using override-web.xml
-You can specify the `override-web.xml` to use for an individual web application, in that webapp's xref:jetty-web-xml-config[].
+You can specify the `override-web.xml` to use for an individual web application in a deployable xml file located in Jetty webapps folder .
+For example, if you had a webapp named MyApp, you would place a deployable xml file named `myapp.xml` in `${jetty.base}/webapps` which includes an `overrideDescriptor` entry for the `override-web.xml` file.
[source, xml, subs="{sub-order}"]
----
-
...
-
/my/path/to/override-web.xml
...
-
-
----
The equivalent in code is:
[source, java, subs="{sub-order}"]
----
-
import org.eclipse.jetty.webapp.WebAppContext;
...
@@ -58,11 +56,9 @@ import org.eclipse.jetty.webapp.WebAppContext;
//Set the path to the override descriptor, based on your $(jetty.home) directory
wac.setOverrideDescriptor(System.getProperty("jetty.home")+"/my/path/to/override-web.xml");
...
-
-
----
-Alternatively, use the classloader (xref:jetty-classloading[]) to get the path to the override descriptor as a resource.
+Alternatively, you can use the classloader (xref:jetty-classloading[]) to get the path to the override descriptor as a resource.
[[override-using-jetty-maven-plugin]]
==== Using the Jetty Maven Plugin
@@ -71,7 +67,6 @@ Use the `` tag as follows:
[source, xml, subs="{sub-order}"]
----
-
...
@@ -89,8 +84,6 @@ Use the `` tag as follows:
...
-
-
----
[[override-web-xml-additional-resources]]
diff --git a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/webdefault-xml.adoc b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/webdefault-xml.adoc
index 95110c6f8b5..588f5b56a8b 100644
--- a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/webdefault-xml.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/webdefault-xml.adoc
@@ -38,7 +38,7 @@ You can specify a custom `webdefault.xml` for an individual web application in t
[source, xml, subs="{sub-order}"]
----
-
+
...
@@ -46,14 +46,14 @@ You can specify a custom `webdefault.xml` for an individual web application in t
...
-
+
----
The equivalent in code is:
[source, java, subs="{sub-order}"]
----
-
+
import org.eclipse.jetty.webapp.WebAppContext;
...
@@ -64,7 +64,7 @@ import org.eclipse.jetty.webapp.WebAppContext;
wac.setDefaultsDescriptor("/my/path/to/webdefault.xml");
...
-
+
----
Alternatively, you can use a xref:jetty-classloading[] to find the resource representing your custom `webdefault.xml`.
@@ -86,7 +86,7 @@ Similarly, when using the link:#jetty-maven-plugin[Jetty Maven Plugin] you provi
[source, xml, subs="{sub-order}"]
----
-
+
...
@@ -105,7 +105,7 @@ Similarly, when using the link:#jetty-maven-plugin[Jetty Maven Plugin] you provi
...
-
+
----
[[webdefault-xml-additional-resources]]