diff --git a/jetty-documentation/pom.xml b/jetty-documentation/pom.xml
index 69af45cad111..5fb64aae8bb4 100644
--- a/jetty-documentation/pom.xml
+++ b/jetty-documentation/pom.xml
@@ -1,145 +1,21 @@
- 4.0.0
org.eclipse.jetty
jetty-project
9.4.35-SNAPSHOT
+
+ 4.0.0
jetty-documentation
Jetty :: Documentation
pom
-
- ${project.build.directory}/current
- ${project.version}
-
+
-
- maven-resources-plugin
-
-
- copy-assets
- process-resources
-
- copy-resources
-
-
-
-
- src/main/resources
-
- **
-
-
-
- ${html.directory}
-
-
-
-
org.asciidoctor
asciidoctor-maven-plugin
-
-
- output-html
- compile
-
- process-asciidoc
-
-
- docbook
- book
- index.adoc
-
- attributes+
-
- true
- true
- true
- ${project.version}
- https://eclipse.org/jetty/javadoc/${javadoc.version}
- https://download.eclipse.org/jetty/stable-9/xref
- ${basedir}/..
- https://github.com/eclipse/jetty.project/tree/jetty-9.4.x
- https://repo1.maven.org/maven2
- ${project.version}
-
-
-
-
-
-
- com.agilejava.docbkx
- docbkx-maven-plugin
- 2.0.17
-
-
- html
- compile
-
- generate-html
-
-
- css/docbook.css
- ${project.basedir}/src/main/docbkx-stylesheet/html/docbook.xsl
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- ${project.build.directory}/generated-docs
- index.xml
- ${project.build.directory}/docbkx/generated
- true
- true
-
-
-
- net.sf.docbook
- docbook-xml
- 5.1b4-all
- resources
- zip
- runtime
-
-
- net.sf.xslthl
- xslthl
- 2.1.3
- runtime
-
-
- org.eclipse.jetty.toolchain
- jetty-xslt-tools
- 1.3
- runtime
-
-
maven-assembly-plugin
@@ -160,85 +36,4 @@
-
-
-
- generate-pdf
-
-
-
- com.agilejava.docbkx
- docbkx-maven-plugin
-
-
- generate-pdf
- compile
-
- generate-pdf
-
-
- index.xml
- 1
- A4
- src/main/docbkx-stylesheet/fo/docbook.xsl
-
-
-
-
-
- net.sf.offo
- fop-hyph
- 1.2
- runtime
-
-
-
-
- org.asciidoctor
- asciidoctor-maven-plugin
-
-
- org.asciidoctor
- asciidoctorj-pdf
- 1.5.0-alpha.11
-
-
-
-
- output-pdf
- generate-sources
-
- process-asciidoc
-
-
- pdf
- rouge
- index.adoc
-
-
- ${project.version}
- true
- true
- true
- ${project.version}
- https://download.eclipse.org/jetty/stable-9/apidocs
- https://download.eclipse.org/jetty/stable-9/xref
- ${basedir}/../jetty.project/
- https://github.com/eclipse/jetty.project/tree/jetty-9.4.x
- font
-
-
-
- -
-
-
-
-
-
-
-
-
-
-
+
\ No newline at end of file
diff --git a/jetty-documentation/src/main/asciidoc/administration/alpn/alpn.adoc b/jetty-documentation/src/main/asciidoc/administration/alpn/alpn.adoc
index dc85090c54f0..278fe27a6aa3 100644
--- a/jetty-documentation/src/main/asciidoc/administration/alpn/alpn.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/alpn/alpn.adoc
@@ -90,19 +90,18 @@ or alternatively you need the link:#alpn-openjdk8-agent[Jetty ALPN agent].
In the case of the Jetty ALPN boot library, start the JVM as follows:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
java -Xbootclasspath/p: ...
----
Where `path_to_alpn_boot_jar` is the path on the file system for the `alpn-boot` artifact, such as the one at the Maven coordinates `org.mortbay.jetty.alpn:alpn-boot`.
-____
[IMPORTANT]
+====
Be certain to get the
link:#alpn-versions[ALPN boot artifact version that matches the version of your JRE].
-____
-
+====
[[alpn-openjdk8-agent]]
==== ALPN agent and OpenJDK 8
@@ -121,13 +120,13 @@ transforms, if necessary, the relevant OpenJDK classes to provide the ALPN suppo
To use the Jetty ALPN agent, start the JVM as follows:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
java -javaagent: ...
----
-____
[NOTE]
+====
The Jetty ALPN agent works with any Java 8 version. It is _required_ if you use
an OpenJDK version up to `1.8.0_242` included, and it is _optional_ if you use an
OpenJDK version equal or greater than `1.8.0_252`.
@@ -135,8 +134,7 @@ OpenJDK version equal or greater than `1.8.0_252`.
The Jetty ALPN agent can be left on the command line even when using an OpenJDK version
equal or greater than `1.8.0_252` but we recommend to remove it from the command line
when you use OpenJDK `1.8.0_252` or later.
-____
-
+====
[[alpn-conscrypt]]
==== ALPN and Conscrypt
@@ -166,19 +164,18 @@ This jar contains a `Fragment-Host` directive that ensures the ALPN classes will
You can download the https://repo1.maven.org/maven2/org/eclipse/jetty/osgi/jetty-osgi-alpn/[jetty-osgi-alpn jar] from Maven Central.
-____
[NOTE]
+====
OSGi *requires* a `ServiceLoader` implementation for Jetty to function properly.
OSGi leverages http://aries.apache.org/modules/spi-fly.html[Apache Aries SPI Fly] for this functionality.
You can read more about OSGi and `ServiceLoader` http://blog.osgi.org/2013/02/javautilserviceloader-in-osgi.html[here.]
-____
-
+====
[[alpn-troubleshooting]]
==== ALPN Troubleshooting
When starting the Jetty server, especially when using Jetty embedded, it may be possible that you see an error similar to this:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
IllegalStateException: no ALPN processor
----
@@ -217,7 +214,7 @@ Refer to `ALPN` Javadocs and to the examples below for further details about cli
[[alpn-openjdk8-client-example]]
==== Client Example
-[source, java, subs="{sub-order}"]
+[source, java]
----
SSLContext sslContext = ...;
SSLSocket sslSocket = (SSLSocket)context.getSocketFactory().createSocket("localhost", server.getLocalPort());
@@ -257,7 +254,7 @@ The ALPN implementation calls `ALPN.ClientProvider` methods `protocols()`, `unsu
The example for `SSLEngine` is identical, and you just need to replace the `SSLSocket` instance with an `SSLEngine` instance.
-[source, java, subs="{sub-order}"]
+[source, java]
----
SSLEngine sslEngine = ...;
ALPN.put(sslEngine, new ALPN.ServerProvider()
@@ -294,7 +291,7 @@ Failing to do so will cause a memory leak.
You can write and run unit tests that use the ALPN implementation.
The solution that we use with Maven is to specify an additional command line argument to the Surefire plugin:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -328,9 +325,9 @@ The solution that we use with Maven is to specify an additional command line arg
You can enable debug logging for the ALPN implementation in this way:
-....
+----
ALPN.debug = true;
-....
+----
Since the ALPN class is in the boot classpath, we chose not to use logging libraries because we do not want to override application logging library choices; therefore the logging is performed directly on `System.err`.
@@ -427,20 +424,20 @@ This section is for Jetty developers that need to update the ALPN implementation
Clone the OpenJDK repository with the following command:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ hg clone https://hg.openjdk.java.net/jdk8u/jdk8u jdk8u
$ cd !$
$ ./get_source.sh
-....
+----
To update the source to a specific tag, use the following command:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ ./make/scripts/hgforest.sh update
-....
+----
The list of OpenJDK tags can be obtained from this page:
https://hg.openjdk.java.net/jdk8u/jdk8u/tags[OpenJDK 8 Tags].
diff --git a/jetty-documentation/src/main/asciidoc/administration/annotations/quick-annotations-setup.adoc b/jetty-documentation/src/main/asciidoc/administration/annotations/quick-annotations-setup.adoc
index 5f848f838300..0706d2d783e4 100644
--- a/jetty-documentation/src/main/asciidoc/administration/annotations/quick-annotations-setup.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/annotations/quick-annotations-setup.adoc
@@ -39,7 +39,7 @@ Below is an example application that sets up the standard `test-spec.war` webapp
It can also be found in the Jetty GitHub repository on the examples/embedded page as link:{GITBROWSEURL}/examples/embedded/src/main/java/org/eclipse/jetty/embedded[`ServerWithAnnotations.java`.]
Note that the `test-spec.war` uses not only annotations, but also link:#jndi[JNDI], so this example also enables their processing (via the link:#jndi-configuration-classes[org.eclipse.jetty.plus.webapp.EnvConfiguration], link:#jndi-configuration-classes[org.eclipse.jetty.plus.webapp.PlusConfiguration] and their related jars).
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ServerWithAnnotations.java[]
----
diff --git a/jetty-documentation/src/main/asciidoc/administration/annotations/using-annotations-embedded.adoc b/jetty-documentation/src/main/asciidoc/administration/annotations/using-annotations-embedded.adoc
index 5aaabebb45b8..a0de5e94c000 100644
--- a/jetty-documentation/src/main/asciidoc/administration/annotations/using-annotations-embedded.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/annotations/using-annotations-embedded.adoc
@@ -24,10 +24,10 @@
You will need to place the following Jetty jar files onto the classpath of your application.
You can obtain them from the https://www.eclipse.org/jetty/download.html[Jetty distribution], or the https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-annotations[Maven repository]:
-....
+----
jetty-plus.jar
jetty-annotations.jar
-....
+----
You will also need the http://asm.ow2.org/[asm] jar, which you can obtain from link:{MVNCENTRAL}/org/eclipse/jetty/orbit/org.objectweb.asm/3.3.1.v201105211655/org.objectweb.asm-3.3.1.v201105211655.jar[this link.]
@@ -39,7 +39,7 @@ The example also adds in the configuration classes that are responsible for JNDI
The code is as follows:
-[source, java, subs="{sub-order}"]
+[source, java]
----
import org.eclipse.jetty.security.HashLoginService;
import org.eclipse.jetty.server.Server;
@@ -101,7 +101,7 @@ On lines 30, 33 and 37 JNDI resources that we will be able to reference with @Re
With the setup above, a servlet that uses annotations and Jetty will honour the annotations when the webapp is deployed can be created:
-[source, java, subs="{sub-order}"]
+[source, java]
----
import javax.annotation.security.DeclareRoles;
import javax.annotation.security.RunAs;
diff --git a/jetty-documentation/src/main/asciidoc/administration/annotations/using-annotations.adoc b/jetty-documentation/src/main/asciidoc/administration/annotations/using-annotations.adoc
index 3d26ce6f9799..bb8489256689 100644
--- a/jetty-documentation/src/main/asciidoc/administration/annotations/using-annotations.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/annotations/using-annotations.adoc
@@ -119,13 +119,12 @@ By default Jetty will call them in the following order:
As is the case with annotation scanning, the link:#using-extra-classpath-method[extraClasspath] is fully considered for `ServletContainerInitializer` callbacks. `ServletContainerInitializer` derived from a classes directory on the `extraClasspath` and jars from an `extraClasspath` for the webapp are called in step 2 and 3, respectively.
-____
[NOTE]
+====
As of Jetty-9.4.4, unless the `web.xml` is version 3.0 or greater, only `ServletContainerInitializers` that are on the container classpath will be discovered.
Users wishing to use `ServletContainerInitializers` from within the webapp with older versions of `web.xml` must either upgrade their `web.xml` version, or call `WebAppContext.setConfigurationDiscovered(true)` either programmatically or in xml.
Upgrading the `web.xml` version is preferable.
-____
-
+====
===== Controlling the order of ServletContainerInitializer invocation
If you need `ServletContainerInitializer` classes called in a specific order that is different from that outlined above, you can use the link:#context_attributes[context attribute] `org.eclipse.jetty.containerInitializerOrder`.
@@ -135,7 +134,7 @@ It will match all `ServletContainerInitializer` classed not explicitly named in
Here is an example, setting the context attribute in code (although you can also do the link:#intro-jetty-configuration-webapps[same in xml]):
-[source, java, subs="{sub-order}"]
+[source, java]
----
WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerOrder",
@@ -154,7 +153,7 @@ In this case, you can define the `org.eclipse.jetty.containerInitializerExclusio
This is a regular expression that defines http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html[patterns] of classnames that you want to exclude.
Here's an example, setting the context attribute in code, although you may do exactly the link:#intro-jetty-configuration-webapps[same in xml]:
-[source, java, subs="{sub-order}"]
+[source, java]
----
WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerExclusionPattern",
diff --git a/jetty-documentation/src/main/asciidoc/administration/extras/cross-origin-filter.adoc b/jetty-documentation/src/main/asciidoc/administration/extras/cross-origin-filter.adoc
index 25f4c665cb94..b239815dcae8 100644
--- a/jetty-documentation/src/main/asciidoc/administration/extras/cross-origin-filter.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/cross-origin-filter.adoc
@@ -79,7 +79,7 @@ Default value is the empty list.
A typical configuration could be:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/administration/extras/debug-handler.adoc b/jetty-documentation/src/main/asciidoc/administration/extras/debug-handler.adoc
index b0b330beae6d..63a8088c2993 100644
--- a/jetty-documentation/src/main/asciidoc/administration/extras/debug-handler.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/debug-handler.adoc
@@ -38,7 +38,7 @@ The debug handler can be added to Jetty by activating the debug module.
==== Embedded usage
-[source, java, subs="{sub-order}"]
+[source, java]
----
Server server = new Server(8080);
RolloverFileOutputStream outputStream = new RolloverFileOutputStream("MeinLogPfad/yyyy_mm_dd.request.log", true,10);
diff --git a/jetty-documentation/src/main/asciidoc/administration/extras/default-handler.adoc b/jetty-documentation/src/main/asciidoc/administration/extras/default-handler.adoc
index 2d313f72a26c..79c248173ef0 100644
--- a/jetty-documentation/src/main/asciidoc/administration/extras/default-handler.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/default-handler.adoc
@@ -34,12 +34,12 @@ As in the example below, if a resource to be served is not matched within the re
This class is a useful template to either extend and embrace or simply provide a similar implementation for customizing to your needs.
There is also an link:#error-handler[Error Handler] that services errors related to the servlet api specification, so it is best to not get the two confused.
-_____
[NOTE]
+====
The `DefaultHandler` will also handle serving out the `flav.ico` file should a request make it through all of the other handlers without being resolved.
-_____
+====
-[source, java, subs="{sub-order}"]
+[source, java]
----
Server server = new Server(8080);
HandlerList handlers = new HandlerList();
diff --git a/jetty-documentation/src/main/asciidoc/administration/extras/dos-filter.adoc b/jetty-documentation/src/main/asciidoc/administration/extras/dos-filter.adoc
index d0acb63763e2..55494a9ee382 100644
--- a/jetty-documentation/src/main/asciidoc/administration/extras/dos-filter.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/dos-filter.adoc
@@ -55,7 +55,7 @@ Place the configuration in a webapp's `web.xml` or `jetty-web.xml`.
The default configuration allows 25 requests per connection at a time, servicing more important requests first, and queuing up the rest.
This example allow 30 requests at a time:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
DoSFilter
diff --git a/jetty-documentation/src/main/asciidoc/administration/extras/gzip-filter.adoc b/jetty-documentation/src/main/asciidoc/administration/extras/gzip-filter.adoc
index c80e05606b95..987553af2c3e 100644
--- a/jetty-documentation/src/main/asciidoc/administration/extras/gzip-filter.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/gzip-filter.adoc
@@ -37,12 +37,11 @@ Some user-agents might be excluded from compression to avoid common browser bugs
The `GzipHandler` can be added to the entire server by enabling the `gzip.mod` module.
It may also be added to individual contexts in a context xml file.
-____
[NOTE]
+====
Jetty 9 only compresses using GZip.
Using deflate HTTP compression is not supported and will not function.
-____
-
+====
[[gzip-filter-rules]]
==== Gzip Rules
@@ -63,13 +62,11 @@ The link:#default-servlet[DefaultServlet] is capable of serving pre-compressed s
The `GzipHandler` installs an output interceptor which passes through to the `DefaultServlet`.
If the content served by `DefaultServlet` is already compressed, the `GzipHandler` does nothing; if it is not compressed, the content is compressed on-the-fly.
-____
[NOTE]
+====
Automatic precompression by the `DefaultServlet` can be configured.
Read more about the `DefaultServlet` link:#default-servlet[here.]
-____
-
-
+====
[[gzip-filter-init]]
==== Gzip Configuration
diff --git a/jetty-documentation/src/main/asciidoc/administration/extras/header-filter.adoc b/jetty-documentation/src/main/asciidoc/administration/extras/header-filter.adoc
index 41d54dedbdd9..07ada8897660 100644
--- a/jetty-documentation/src/main/asciidoc/administration/extras/header-filter.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/header-filter.adoc
@@ -50,12 +50,11 @@ This filter will perform the following actions on each response:
* Set the Expires header to approximately one year in the future.
* Add a Date header with the current system time.
-____
[NOTE]
+====
Each action must be separated by a comma.
-____
-
-[source, xml, subs="{sub-order}"]
+====
+[source, xml]
----
HeaderFilter
diff --git a/jetty-documentation/src/main/asciidoc/administration/extras/moved-context-handler.adoc b/jetty-documentation/src/main/asciidoc/administration/extras/moved-context-handler.adoc
index 8de56752ccfc..f8c4accdeb44 100644
--- a/jetty-documentation/src/main/asciidoc/administration/extras/moved-context-handler.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/moved-context-handler.adoc
@@ -45,7 +45,7 @@ You create a new xref:configuring-contexts[context xml] file in `{$jetty/.base}/
Below is an example.
This is a permanent redirection, which also preserves `pathinfo` and query strings on the redirect:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/administration/extras/qos-filter.adoc b/jetty-documentation/src/main/asciidoc/administration/extras/qos-filter.adoc
index d2c407daf834..0f48035d3752 100644
--- a/jetty-documentation/src/main/asciidoc/administration/extras/qos-filter.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/qos-filter.adoc
@@ -83,7 +83,7 @@ Place the configuration in a webapp's `web.xml` or `jetty-web.xml`.
The default configuration processes ten requests at a time, servicing more important requests first and queuing up the rest.
This example processes fifty requests at a time:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
QoSFilter
@@ -126,7 +126,7 @@ This allows a context external mechanism (for example, JMX via `ContextHandler.M
You can use the `` syntax to map the QoSFilter to a servlet, either by using the servlet name, or by using a URL pattern.
In this example, a URL pattern applies the QoSFilter to every request within the web application context:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
QoSFilter
@@ -147,7 +147,7 @@ To customize the priority, subclass QoSFilter and then override the `getPriority
You can then use this subclass as your QoS filter.
Here's an example:
-[source, java, subs="{sub-order}"]
+[source, java]
----
public class ParsePriorityQoSFilter extends QoSFilter
{
diff --git a/jetty-documentation/src/main/asciidoc/administration/extras/resource-handler.adoc b/jetty-documentation/src/main/asciidoc/administration/extras/resource-handler.adoc
index 71831a46e248..87bd303edd31 100644
--- a/jetty-documentation/src/main/asciidoc/administration/extras/resource-handler.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/resource-handler.adoc
@@ -31,16 +31,14 @@
This handler will serve static content and handle If-Modified-Since headers and is suitable for simple serving of static content.
-____
[IMPORTANT]
+====
There is no caching done with this handler, so if you are looking for a more fully featured way of serving static content look to the xref:default-servlet[].
-____
-
-____
+====
[NOTE]
+====
Requests for resources that do not exist are let pass (Eg no 404's).
-____
-
+====
==== Improving the Look and Feel
The resource handler has a default stylesheet which you can change by calling `setStyleSheet(String location)` with the location of a file on the system that it can locate through the resource loading system.
@@ -51,7 +49,7 @@ The default css is called `jetty-dir.css` and is located in the `jetty-util` pac
The following is an example of a split fileserver, able to serve static content from multiple directory locations.
Since this handler does not return 404's on content you are able to iteratively try multiple resource handlers to resolve content.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/SplitFileServer.java[]
----
diff --git a/jetty-documentation/src/main/asciidoc/administration/extras/rewrite-handler.adoc b/jetty-documentation/src/main/asciidoc/administration/extras/rewrite-handler.adoc
index 6f914607562b..bc57d9644c57 100644
--- a/jetty-documentation/src/main/asciidoc/administration/extras/rewrite-handler.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/rewrite-handler.adoc
@@ -31,21 +31,21 @@ The most common use is to rewrite request URIs, but it is capable of much more:
The standard Jetty distribution bundle contains the `jetty-rewrite` link:#startup-modules[module], so all you need to do is to enable it using one of the link:#start-jar[module commands], eg:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ java -jar start.jar --add-to-start=rewrite
-....
+----
-_____
[NOTE]
+====
If you are running the standard Jetty distribution with the sample test webapp, there will be a demo of the rewrite module at http://localhost:8080/test/rewrite/
-_____
+====
==== Usage
The rewrite module enables the following Jetty xml config file on the execution path:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/jetty-rewrite/src/main/config/etc/jetty-rewrite.xml[]
----
@@ -54,7 +54,7 @@ As the commented out code shows, you configure the `RewriteHandler` by adding va
There is an example of link:#rewrite-rules[rules] configuration in the standard distribution in the `demo-base/etc/demo-rewrite-rules.xml` file:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/etc/demo-rewrite-rules.xml[]
----
@@ -63,7 +63,7 @@ include::{SRCDIR}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base
This is an example for embedded Jetty, which does something similar to the configuration file example above:
-[source, java, subs="{sub-order}"]
+[source, java]
----
Server server = new Server();
diff --git a/jetty-documentation/src/main/asciidoc/administration/extras/shutdown-handler.adoc b/jetty-documentation/src/main/asciidoc/administration/extras/shutdown-handler.adoc
index e3f4bb876aae..7315eaa5f604 100644
--- a/jetty-documentation/src/main/asciidoc/administration/extras/shutdown-handler.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/shutdown-handler.adoc
@@ -36,7 +36,7 @@ If `_exitJvm` is set to true a hard `System.exit()` call is being made.
This is an example of how you can setup this handler directly with the Server.
It can also be added as a part of handler chain or collection.
-[source, java, subs="{sub-order}"]
+[source, java]
----
Server server = new Server(8080);
HandlerList handlers = new HandlerList();
@@ -48,7 +48,7 @@ It can also be added as a part of handler chain or collection.
This is an example that you can use to call the shutdown handler from within java.
-[source, java, subs="{sub-order}"]
+[source, java]
----
public static void attemptShutdown(int port, String shutdownCookie) {
try {
diff --git a/jetty-documentation/src/main/asciidoc/administration/extras/statistics-handler.adoc b/jetty-documentation/src/main/asciidoc/administration/extras/statistics-handler.adoc
index 39a06d1b5738..17591ffe2a0f 100644
--- a/jetty-documentation/src/main/asciidoc/administration/extras/statistics-handler.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/extras/statistics-handler.adoc
@@ -35,18 +35,18 @@ Jetty currently has two main statistics collection mechanisms:
* The `StatisticsHandler` class may be used to collect statistics for HTTP requests.
The `StatisticsHandler` and `ConnectionStatistics` are not included in the default Jetty configuration, these need to be configured manually or enabled using the Jetty `stats` module on the command line.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ java -jar {$jetty.home}/start.jar --add-to-start=stats
-....
+----
In addition to these, the `SessionHandler` and `DefaultSessionCache` classes collect statistics for sessions.
These statistics are enabled by default and are accessible via JMX interface.
-_____
[NOTE]
+====
To view statistics, you have to be able to connect to Jetty using either JConsole or some other JMX agent. See xref:using-jmx[] for more information.
-_____
+====
[[request-statistics]]
==== Request Statistics
@@ -58,7 +58,7 @@ You can enable the `StatisticsHandler` by activating the `stats` modules on the
Alternately, if you are making multiple changes to the Jetty configuration, you could include statistics handler configuration into your own Jetty xml configuration.
The following fragment shows how to configure a top level statistics handler:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -77,7 +77,7 @@ The current and maximum number of connections are the only "live" statistics.
The following example shows how to turn on connection statistics in the Jetty XML format.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -91,7 +91,7 @@ The following example shows how to turn on connection statistics in the Jetty XM
A special variant of `ConnectionStatistics` called `IncludeExcludeConnectionStatistics` allows you to refine which types of connection you want to collect statistics for.
The following example shows how this can be used to record statistics only for WebSocket connections.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/administration/fastcgi/configuring-fastcgi.adoc b/jetty-documentation/src/main/asciidoc/administration/fastcgi/configuring-fastcgi.adoc
index aeace6bc3703..2a459c2920be 100644
--- a/jetty-documentation/src/main/asciidoc/administration/fastcgi/configuring-fastcgi.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/fastcgi/configuring-fastcgi.adoc
@@ -31,12 +31,12 @@ Refer to xref:jetty-downloading[] for more information about how to install Jett
The fourth step is to create a Jetty base directory (see xref:startup-base-and-home[]), called in the following `$JETTY_BASE`, where you setup the configuration needed to support FastCGI in Jetty, and configure the `fcgi`, `http` and `deploy` modules, so that Jetty will be able to accept HTTP requests from browsers, convert them in FastCGI, and proxy them to `php-fpm`:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ mkdir -p /usr/jetty/wordpress
$ cd /usr/jetty/wordpress
$ java -jar $JETTY_HOME/start.jar --add-to-start=fcgi,http,deploy
-....
+----
Therefore `$JETTY_BASE=/usr/jetty/wordpress`.
@@ -46,7 +46,7 @@ For FastCGI there is no web application that needs developed - all the work has
As such you only need to deploy a Jetty context XML file that configures the web application directly.
Copy and paste the following content as `$JETTY_BASE/webapps/jetty-wordpress.xml`:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -138,11 +138,11 @@ Refer to the link:{JDURL}/org/eclipse/jetty/fcgi/server/proxy/FastCGIProxyServle
The last step is to start Jetty (see xref:startup[]) and navigate to `http://localhost:8080` with your browser and enjoy WordPress:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ cd $JETTY_BASE
$ java -jar /opt/jetty/start.jar
-....
+----
[[configuring-fastcgi-http2]]
==== Configuring Jetty to Proxy HTTP/2 to FastCGI
@@ -151,11 +151,11 @@ In order to configure Jetty to listen for HTTP/2 requests from clients that are
Enabling the `http2` is easy; in additions to the modules you have enabled above, add the `http2` module:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2
-....
+----
The command above adds the `http2` module (and its dependencies) to the existing modules and uses the default Jetty keystore to provide the key material required by TLS.
You will want to use your own keystore with your own private key and certificate for your own domain.
@@ -171,10 +171,10 @@ These will setup a clear text connector on port 8080 for HTTP/1.1 and a TLS conn
At this point, you can start Jetty (see xref:startup[]), hit `http://localhost:8080` with your browser and enjoy WordPress via HTTP/2 using a HTTP/2 enabled browser:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar
-....
+----
If you don't have a HTTP/2 enabled browser, WordPress will still be available over HTTP/1.1.
diff --git a/jetty-documentation/src/main/asciidoc/administration/http2/configuring-haproxy.adoc b/jetty-documentation/src/main/asciidoc/administration/http2/configuring-haproxy.adoc
index c82ab8f63a56..a323959308d2 100644
--- a/jetty-documentation/src/main/asciidoc/administration/http2/configuring-haproxy.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/http2/configuring-haproxy.adoc
@@ -34,19 +34,18 @@ The instructions that follow are for Linux.
You will need HAProxy 1.5 or later, because it provides support for SSL and ALPN, both required by HTTP/2. Most Linux distributions have the HAProxy package available to be installed out of the box. For example on Ubuntu 15.04:
-[source,screen, subs="{sub-order}"]
-....
+[source,screen]
+----
$ sudo apt-get install haproxy
-....
+----
Alternatively you can download the HAProxy source code and build it on your environment by following the README bundled with the HAProxy source code tarball.
-____
[NOTE]
+====
HAProxy supports ALPN only if built with OpenSSL 1.0.2 or greater.
Use `haproxy -vv` to know with which OpenSSL version HAProxy has been built.
-____
-
+====
[[http2-haproxy-ssl]]
==== Setup SSL for HAProxy
@@ -62,8 +61,8 @@ HAProxy will need a single file containing the X509 certificates and the private
Let's use `keytool` to generate a self signed certificate:
-[source,screen, subs="{sub-order}"]
-....
+[source,screen]
+----
$ keytool -genkeypair -keyalg RSA -keystore keystore.p12 -storetype pkcs12 -storepass storepwd -ext SAN=DNS:domain.com
What is your first and last name?
[Unknown]: *.domain.com
@@ -79,31 +78,31 @@ What is the two-letter country code for this unit?
[Unknown]: IT
Is CN=*.domain.com, OU=Unit, O=Domain, L=Torino, ST=TO, C=IT correct?
[no]: yes
-....
+----
The above command will generate a self signed certificate and private key for `domain.com` and subdomains, stored in the `keystore.p12` file in PKCS#12 format.
We need to extract the certificate and the private key in PEM format.
To extract the certificate into `certificate.pem`:
-[source,screen, subs="{sub-order}"]
-....
+[source,screen]
+----
$ keytool -exportcert -keystore keystore.p12 -storetype pkcs12 -storepass storepwd -rfc -file certificate.pem
-....
+----
To export the private key into `private_key.pem`:
-[source,screen, subs="{sub-order}"]
-....
+[source,screen]
+----
$ openssl pkcs12 -in keystore.p12 -nodes -nocerts -out private_key.pem -passin pass:storepwd
-....
+----
At this point you just need to concatenate the two files into one, in the correct order:
-[source,screen, subs="{sub-order}"]
-....
+[source,screen]
+----
$ cat certificate.pem private_key.pem > domain.pem
-....
+----
The `domain.pem` file will be used later by HAProxy.
@@ -113,8 +112,8 @@ The `domain.pem` file will be used later by HAProxy.
Now we can setup `haproxy.cfg` to configure HAProxy.
This is a minimal configuration:
-[source, ,subs="{sub-order}"]
-....
+[source]
+----
global
tune.ssl.default-dh-param 1024
@@ -137,7 +136,7 @@ default_backend be_http
backend be_http
mode tcp
server domain 127.0.0.1:8282
-....
+----
The HAProxy configuration file works in the following way.
The `fe_http` front-end accepts connections on port 80 and redirects them to use the `https` scheme.
@@ -157,32 +156,31 @@ Since the `http2c` module depends on the `http` module, the `http` module will b
Additionally, you will also enable the `deploy` module to be able to deploy a sample web application:
-[source,screen, subs="{sub-order}"]
-....
+[source,screen]
+----
$ JETTY_BASE=haproxy-jetty-http2
$ mkdir $JETTY_BASE
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2c,deploy
-....
+----
Now let's deploy a demo web application and start Jetty:
-[source,screen, subs="{sub-order}"]
-....
+[source,screen]
+----
$ cd $JETTY_BASE
$ cp $JETTY_HOME/demo-base/webapps/async-rest.war $JETTY_BASE/webapps/
$ java -jar $JETTY_HOME/start.jar jetty.http.host=127.0.0.1 jetty.http.port=8282
-....
+----
Now you can browse https://domain.com/async-rest (replace `domain.com` with your own domain, or with `localhost`, to make this example work).
-____
[NOTE]
+====
You want the Jetty connector that listens on port 8282 to be available only to HAProxy, and not to remote clients.
For this reason, you want to specify the `jetty.http.host` property on the command line (or in `start.ini`/ `start.d/http.ini` to make this setting persistent) to bind the Jetty connector only on the loopback interface (127.0.0.1), making it available to HAProxy but not to remote clients.
If your Jetty instance runs on a different machine and/or on a different (sub)network, you may want to adjust both the back-end section of the HAProxy configuration file and the `jetty.http.host` property to match accordingly.
-____
-
+====
Browsers supporting HTTP/2 will connect to HAProxy, which will decrypt the traffic and send it to Jetty.
Likewise, HTTP/1.1 clients will connect to HAProxy, which will decrypt the traffic and send it to Jetty.
diff --git a/jetty-documentation/src/main/asciidoc/administration/http2/configuring-http2.adoc b/jetty-documentation/src/main/asciidoc/administration/http2/configuring-http2.adoc
index 2ac2b6f7dd6a..c2b633cd22a0 100644
--- a/jetty-documentation/src/main/asciidoc/administration/http2/configuring-http2.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/http2/configuring-http2.adoc
@@ -24,8 +24,8 @@ existing connector.
Thus configuring HTTP/2 is a combination of configuring common properties on the connector and HTTP/2 specific properties on the connection factory.
The modules and XML files involved can be seen with the following commands:
-[source,screen, subs="{sub-order}"]
-....
+[source,screen]
+----
$ java -jar $JETTY_HOME/start.jar --list-modules
...
1) alpn-impl
@@ -48,17 +48,16 @@ $ java -jar $JETTY_HOME/start.jar --list-config
...
${jetty.home}/etc/jetty-http2.xml
${jetty.home}/etc/jetty-https.xml
-....
+----
The common properties associated with connectors (host,port, timeouts, etc.) can be set in the module ini files (or `start.ini` if `--add-to-start` was used): `${jetty.base}/start.d/http.ini` and `${jetty.base}/start.d/ssl.ini`.
These properties are instantiated in the associated XML files: `${jetty.home}/etc/jetty-http.xml`; `${jetty.home}/etc/jetty-ssl.xml`, plus the SSL keystore is instantiated in `${jetty.home}/etc/jetty-ssl-context.xml`.
-____
[NOTE]
+====
If you are planning to edit XML files, make sure to copy them to your `{$jetty.base}/etc/` directory before doing so.
The XML files that come with the Jetty distribution should *not* be modified directly.
-____
-
+====
HTTP/2 specific properties can be set in the module ini files: `${jetty.base}/start.d/http2.ini` and `${jetty.base}/start.d/http2c.ini`, which are instantiated in the associated XML files: `${jetty.home}/etc/jetty-http2.xml`; `${jetty.home}/etc/jetty-http2c.xml`, respectively.
Currently there are very few HTTP/2 configuration properties and the default values are reasonable:
diff --git a/jetty-documentation/src/main/asciidoc/administration/http2/configuring-push.adoc b/jetty-documentation/src/main/asciidoc/administration/http2/configuring-push.adoc
index b3a35d00637a..1bc91127d14a 100644
--- a/jetty-documentation/src/main/asciidoc/administration/http2/configuring-push.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/http2/configuring-push.adoc
@@ -24,7 +24,7 @@ This will reduce the amount of round-trips necessary to retrieve all the resourc
HTTP/2 Push can be automated in your application by configuring a link:{JDURL}/org/eclipse/jetty/servlets/PushCacheFilter.html[`PushCacheFilter`] in the `web.xml`, in this way:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
` element to the `` element of the Jetty Maven Plugin:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -124,14 +124,14 @@ Connecting to the remote JVM is a two step process:
The configuration for the RMI registry and the RMI server is specified by a `JMXServiceURL`.
The string format of an RMI `JMXServiceURL` is:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
service:jmx:rmi://:/jndi/rmi://:/jmxrmi
----
Default values are:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
rmi_server_host = localhost
rmi_server_port = 1099
@@ -149,7 +149,7 @@ If you need to allow JMX remote access through a firewall, you must open both th
Examples:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
service:jmx:rmi:///jndi/rmi:///jmxrmi
rmi_server_host = local host address
@@ -183,7 +183,7 @@ This is especially important when binding the RMI server host to the loopback ad
Similarly to link:#jmx-standalone-jetty[enabling JMX in a standalone Jetty server], you enable the `jmx-remote` module:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ cd ${jetty.base}
$ java -jar {$jetty.home}/start.jar --add-to-start=jmx-remote
@@ -193,7 +193,7 @@ $ java -jar {$jetty.home}/start.jar --add-to-start=jmx-remote
When running Jetty embedded into an application, create and configure a `ConnectorServer`:
-[source, java, subs="{sub-order}"]
+[source, java]
----
Server server = new Server();
@@ -217,7 +217,7 @@ For a complete guide to controlling authentication and authorization in JMX, see
To authorize access to the `JMXConnectorServer` you can use this configuration, where the `jmx.password` and `jmx.access` files have the format specified in the blog entry above:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -251,7 +251,7 @@ To authorize access to the `JMXConnectorServer` you can use this configuration,
Similarly, in code:
-[source, java, subs="{sub-order}"]
+[source, java]
----
JMXServiceURL jmxURL = new JMXServiceURL("rmi", null, 1099, "/jndi/rmi:///jmxrmi");
Map env = new HashMap<>();
@@ -269,7 +269,7 @@ The JMX communication via RMI happens by default in clear-text.
It is possible to configure the `ConnectorServer` with a `SslContextFactory` so that the JMX communication via RMI is encrypted:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -288,7 +288,7 @@ It is possible to configure the `ConnectorServer` with a `SslContextFactory` so
Similarly, in code:
-[source, java, subs="{sub-order}"]
+[source, java]
----
SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
sslContextFactory.setKeyStorePath("/path/to/keystore");
@@ -313,7 +313,7 @@ If that is not the case (for example the certificate is self-signed), then you n
For example, trying to connect using the JDK standard `JMXConnector` with both the RMI server and the RMI registry to `domain.com`:
-[source, java, subs="{sub-order}"]
+[source, java]
----
// System properties necessary for an RMI client to trust a self-signed certificate.
System.setProperty("javax.net.ssl.trustStore", "/path/to/trustStore");
@@ -331,7 +331,7 @@ try (JMXConnector client = JMXConnectorFactory.connect(jmxURL, clientEnv))
Similarly, to launch JMC:
-[source, java, subs="{sub-order}"]
+[source, java]
----
$ jmc -vmargs -Djavax.net.ssl.trustStore=/path/to/trustStore -Djavax.net.ssl.trustStorePassword=secret
----
@@ -347,7 +347,7 @@ In this case you want to configure the `ConnectorServer` with a `JMXServiceURL`
Then you setup the local port forwarding with the SSH tunnel:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ ssh -L 1099:localhost:1099 @
----
diff --git a/jetty-documentation/src/main/asciidoc/administration/jndi/jndi-configuration.adoc b/jetty-documentation/src/main/asciidoc/administration/jndi/jndi-configuration.adoc
index c2e9217977c7..2de5e4bd5bc1 100644
--- a/jetty-documentation/src/main/asciidoc/administration/jndi/jndi-configuration.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/jndi/jndi-configuration.adoc
@@ -25,7 +25,7 @@
Sometimes it is useful to pass configuration information to a webapp at runtime that you either cannot or cannot conveniently code into a `web.xml` env-entry.
In such cases, you can use the `org.eclipse.jetty.plus.jndi.EnvEntry` class, and even override an entry of the same name in `web.xml`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -57,7 +57,7 @@ Be aware that if you take advantage of this feature, your web application is __n
To use the `env-entry` configured above, use code in your `servlet/filter/etc.`, such as:
-[source, java, subs="{sub-order}"]
+[source, java]
----
import javax.naming.InitialContext;
@@ -103,7 +103,7 @@ Jetty can use any DataSource implementation available on its classpath.
In this example, the DataSource is from the http://db.apache.org/derby[Derby] relational database, but you can use any implementation of a `javax.sql.DataSource`.
This example configures it as scoped to a web app with the id of __wac__:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -124,7 +124,7 @@ If you do not have the appropriate `resource-ref` set up in your `web.xml`, it i
Here's an example `web.xml` declaration for the datasource above:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
jdbc/myds
@@ -135,7 +135,7 @@ Here's an example `web.xml` declaration for the datasource above:
To look up your DataSource in your `servlet/filter/etc.`:
-[source, java, subs="{sub-order}"]
+[source, java]
----
import javax.naming.InitialContext;
import javax.sql.DataSource;
@@ -152,12 +152,11 @@ public class MyClass {
}
----
-____
[NOTE]
+====
Careful! When configuring Resources, ensure that the type of object you configure matches the type of object you expect to look up in `java:comp/env`.
For database connection factories, this means that the object you register as a Resource _must_ implement the `javax.sql.DataSource` interface.
-____
-
+====
For more examples of datasource configurations, see xref:jndi-datasource-examples[].
[[configuring-jms-queues-topics-connectionfactories]]
@@ -167,7 +166,7 @@ Jetty can bind any implementation of the JMS destinations and connection factori
You just need to ensure the implementation Jars are available on Jetty's classpath.
Here is an example of binding an http://activemq.apache.org[ActiveMQ] in-JVM connection factory:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -184,7 +183,7 @@ Here is an example of binding an http://activemq.apache.org[ActiveMQ] in-JVM con
The entry in `web.xml` would be:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
jms/connectionFactory
@@ -200,7 +199,7 @@ TODO: put in an example of a QUEUE from progress demo
Jetty also provides infrastructure for access to `javax.mail.Sessions` from within an application:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -226,12 +225,11 @@ Jetty also provides infrastructure for access to `javax.mail.Sessions` from with
This setup creates an instance of the `org.eclipse.jetty.jndi.factories.MailSessionReference` class, calls it's setter methods to set up the authentication for the mail system, and populates a set of Properties, setting them on the `MailSessionReference` instance.
The result is that an application can look up `java:comp/env/mail/Session` at runtime and obtain access to a `javax.mail.Session` that has the necessary configuration to permit it to send email via SMTP.
-____
[TIP]
+====
You can set the password to be plain text, or use Jetty's link:#configuring-security-secure-passwords[Secure Password Obfuscation] (OBF:) mechanism to make the config file a little more secure from prying eyes.
Remember that you cannot use the other Jetty encryption mechanisms of MD5 and Crypt because they do not allow you to recover the original password, which the mail system requires.
-____
-
+====
[[configuring-xa-transactions]]
==== Configuring XA Transactions
@@ -240,7 +238,7 @@ Jetty does not ship with one as standard, but you can plug in the one you prefer
You can configure a transaction manager using the link:{JDURL}/org/eclipse/jetty/plus/jndi/Transaction.html[JNDI Transaction] object in a Jetty config file.
The following example configures the http://www.atomikos.com/[Atomikos] transaction manager:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -257,7 +255,7 @@ For example:
In a context xml file:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -275,7 +273,7 @@ In a context xml file:
In a `web.xml` file:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
jdbc/mydatasource
@@ -293,7 +291,7 @@ For the example above, you can refer to the `jdbc/mydatasource` resource as `jdb
In a context xml file declare `jdbc/mydatasource`:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -312,7 +310,7 @@ In a context xml file declare `jdbc/mydatasource`:
Then in a `WEB-INF/jetty-env.xml` file, link the name `jdbc/mydatasource` to the name you want to reference it as in
`web.xml`, which in this case is `jdbc/mydatasource1`:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -323,7 +321,7 @@ Then in a `WEB-INF/jetty-env.xml` file, link the name `jdbc/mydatasource` to the
Now you can refer to `jdbc/mydatasource1` in the `web.xml` like this:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
jdbc/mydatasource1
diff --git a/jetty-documentation/src/main/asciidoc/administration/jndi/jndi-datasources.adoc b/jetty-documentation/src/main/asciidoc/administration/jndi/jndi-datasources.adoc
index 0ac814b4e090..fb13ed8579bc 100644
--- a/jetty-documentation/src/main/asciidoc/administration/jndi/jndi-datasources.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/jndi/jndi-datasources.adoc
@@ -21,14 +21,13 @@
Here are examples of configuring a JNDI datasource for various databases.
-____
[NOTE]
+====
Read xref:configuring-datasources[] in xref:jndi-configuration[] for more information about configuring datasources.
-____
-
+====
All of these examples correspond to a `resource-ref` in `web.xml`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
My DataSource Reference
@@ -42,11 +41,10 @@ These examples assume that all of the datasources are declared at the JVM scope,
You can configure all JNDI resources in a `jetty.xml` file, a `WEB-INF/jetty-env.xml` file, or a context XML file.
See the section xref:jndi-where-to-declare[] for more information.
-____
[IMPORTANT]
+====
You must provide Jetty with the libraries necessary to instantiate the datasource you have configured by putting the corresponding Jar in `JETTY_HOME/lib/ext`.
-____
-
+====
[[pooling-datasources]]
==== Pooling DataSources
@@ -71,7 +69,7 @@ The following is a list of the pooled datasource examples we have worked with in
Connection pooling, available at http://search.maven.org/remotecontent?filepath=com/zaxxer/HikariCP/1.4.0/HikariCP-1.4.0.jar[HikariCP Download].
All configuration options for HikariCP are described here: https://github.com/brettwooldridge/HikariCP[HikariCP documentation].
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -102,7 +100,7 @@ All configuration options for HikariCP are described here: https://github.com/br
Connection pooling, available at http://jolbox.com/index.html?page=http://jolbox.com/download.html[BoneCP Download].
All configuration options for BoneCP are described here: http://jolbox.com/bonecp/downloads/site/apidocs/com/jolbox/bonecp/BoneCPDataSource.html[BoneCP API].
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -128,7 +126,7 @@ All configuration options for BoneCP are described here: http://jolbox.com/bonec
Connection pooling, available at https://repo1.maven.org/maven2/c3p0/c3p0/0.9.1.2/c3p0-0.9.1.2.jar[c3p0 Jar].
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -149,7 +147,7 @@ Connection pooling, available at https://repo1.maven.org/maven2/c3p0/c3p0/0.9.1.
Connection pooling, available at https://repo1.maven.org/maven2/commons-dbcp/commons-dbcp/1.2/commons-dbcp-1.2.jar[dbcp Jar].
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -171,7 +169,7 @@ Connection pooling, available at https://repo1.maven.org/maven2/commons-dbcp/com
Connection pooling + XA transactions.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -206,7 +204,7 @@ Connection pooling + XA transactions.
Implements `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -226,7 +224,7 @@ Implements `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource`.
Implements `javax.sql.ConnectionPoolDataSource`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -252,7 +250,7 @@ Implements `javax.sql.ConnectionPoolDataSource`.
Implements `javax.sql.ConnectionPoolDataSource`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -288,7 +286,7 @@ The following is a list of the non-pooled datasource examples:
Implements `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -310,7 +308,7 @@ Implements `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource`.
Implements `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -343,7 +341,7 @@ For more information, refer to: http://docs.oracle.com/cd/B14117_01/java.101/b10
Implements `javax.sql.DataSource`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -365,7 +363,7 @@ Implements `javax.sql.DataSource`.
Implements `javax.sql.DataSource`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -387,7 +385,7 @@ Implements `javax.sql.DataSource`.
Implements `javax.sql.DataSource`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/administration/jndi/jndi-embedded.adoc b/jetty-documentation/src/main/asciidoc/administration/jndi/jndi-embedded.adoc
index 2f3c24b311b0..eb880b944e50 100644
--- a/jetty-documentation/src/main/asciidoc/administration/jndi/jndi-embedded.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/jndi/jndi-embedded.adoc
@@ -23,10 +23,10 @@
In addition to the jars that you require for your application, and the jars needed for core Jetty, you will need to place the following jars onto your classpath:
-....
+----
jetty-jndi.jar
jetty-plus.jar
-....
+----
If you are using transactions, you will also need the `javax.transaction` api.
You can obtain this jar link:{MVNCENTRAL}/org/eclipse/jetty/orbit/javax.transaction/1.1.1.v201105210645/javax.transaction-1.1.1.v201105210645.jar[here.]
@@ -39,7 +39,7 @@ Note that this jar also requires the `javax.activation` classes, which is availa
Here is an example class that sets up some JNDI entries and deploys a webapp that references these JNDI entries in code.
We'll use some mocked up classes for the transaction manager and the DataSource in this example for simplicity:
-[source, java, subs="{sub-order}"]
+[source, java]
----
import java.util.Properties;
import org.eclipse.jetty.server.Server;
diff --git a/jetty-documentation/src/main/asciidoc/administration/jndi/quick-jndi-setup.adoc b/jetty-documentation/src/main/asciidoc/administration/jndi/quick-jndi-setup.adoc
index 37739a27ac3d..e5327344e744 100644
--- a/jetty-documentation/src/main/asciidoc/administration/jndi/quick-jndi-setup.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/jndi/quick-jndi-setup.adoc
@@ -23,12 +23,12 @@ If you are using the standard distribution of Jetty, you must enable the _JNDI_
As the _plus_ module depends on the _JNDI_ module, you only need to enable the _plus_ module to enable both.
Assuming you have Jetty installed in `/opt/jetty`, and you have made a link:#startup-base-and-home[jetty base] in `/opt/jetty/my-base`, do:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
cd /opt/jetty
cd my-base
java -jar $JETTY_HOME/start.jar --add-to-start=plus
-....
+----
You can now start Jetty and use JNDI within your webapps.
See link:#using-jndi[Using JNDI] for information on how to add entries to the JNDI environment that Jetty can look up within webapps.
@@ -37,9 +37,9 @@ If you have extra jars associated with your JNDI resources, for example a databa
You will then need to enable the _ext_ module to ensure the jars in the `ext/` directory are on the classpath.
Assuming you have Jetty installed in `/opt/jetty`, and you have made a link:#startup-base-and-home[jetty base] in `/opt/jetty/my-base`, do:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
cd /opt/jetty
cd my-base
java -jar $JETTY_HOME/start.jar --add-to-start=ext
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/jndi/using-jndi.adoc b/jetty-documentation/src/main/asciidoc/administration/jndi/using-jndi.adoc
index ef04e55fb3ea..a146ace5ab48 100644
--- a/jetty-documentation/src/main/asciidoc/administration/jndi/using-jndi.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/jndi/using-jndi.adoc
@@ -24,7 +24,7 @@
You can configure naming resources to reference in a `web.xml` file and access from within the `java:comp/env` naming environment of the webapp during execution.
Specifically, you can configure support for the following `web.xml` elements:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -52,7 +52,7 @@ For the link between a `web.xml` resource name and a naming entry
Declarations of each of these types follow the same general pattern:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -91,7 +91,7 @@ The name is unique across the JVM instance, and is visible to all application co
You represent this scope by a `null` first parameter to the resource declaration.
For example:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -109,7 +109,7 @@ The name is unique to a Server instance, and is only visible to code associated
You represent this scope by referencing the Server instance as the first parameter to the resource declaration.
For example:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -128,7 +128,7 @@ The name is unique to the WebAppContext instance, and is only visible to code as
You represent this scope by referencing the `WebAppContext` instance as the first parameter to the resource declaration.
For example:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-logging.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-logging.adoc
index 48619ca2aa39..ef5d11d04f78 100644
--- a/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-logging.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-logging.adoc
@@ -34,11 +34,10 @@ DEBUG::
IGNORE::
Exception events that you can safely ignore, but useful for some people.
You might see this level as DEBUG under some Java logging framework configurations, where it retains the _ignore_ phrase somewhere in the logging.
-____
[NOTE]
+====
Jetty logging produces no FATAL or SEVERE events.
-____
-
+====
[[selecting-log-framework]]
==== Selecting the Log Framework
@@ -51,12 +50,11 @@ Configure the Jetty logging layer via the `org.eclipse.jetty.util.log.Log` class
* If property `org.eclipse.jetty.util.log.class` is defined, load the class it defines as the logger implementation from the server `classpath`.
* If the class `org.slf4j.Logger` exists in server classpath, the Jetty implementation becomes `org.eclipse.jetty.util.log.Slf4jLog`.
* If no logger implementation is specified, default to `org.eclipse.jetty.util.log.StdErrLog`.
-____
[NOTE]
+====
You can create your own custom logging by providing an implementation of the link:{JDURL}org/eclipse/jetty/util/log/Logger.html[Jetty Logger API].
For an example of a custom logger, see link:{GITBROWSEURL}/jetty-util/src/main/java/org/eclipse/jetty/util/log/JavaUtilLog.java[JavaUtilLog.java].
-____
-
+====
[[configuring-jetty-stderrlog]]
==== The jetty-logging.properties file
diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-request-logs.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-request-logs.adoc
index 92bcd622b673..d0bc866ac9ca 100644
--- a/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-request-logs.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-request-logs.adoc
@@ -28,12 +28,12 @@ There is one entry per request received, and commonly in the standard NCSA forma
A standard request log entry includes the client IP address, date, method, URL, result, size, referrer, user agent and latency.
For example:
-....
+----
123.4.5.6 - - [20/Jul/2016:10:16:17 +0000]
"GET /jetty/tut/XmlConfiguration.html HTTP/1.1"
200 76793 "http://localhost:8080/jetty/tut/logging.html"
"Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.6) Gecko/20040614 Firefox/0.8" 342
-....
+----
[[implementing-request-log]]
==== Implementing a Request Log
@@ -49,7 +49,7 @@ If neither of these options meets your needs, you can implement a custom request
To enable the Request Log module for the entire server via the Jetty distribution, it first needs to be enabled on the command line:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ java -jar ../start.jar --add-to-start=requestlog
@@ -60,15 +60,14 @@ INFO: Base directory was modified
The above command will add a new `requestlog.ini` file to your link:#start-vs-startd[`{$jetty.base}/start.d` directory].
-____
[NOTE]
+====
By default, request logs are not set to be appended, meaning a the log file is wiped clean upon sever restart.
You can change this setting by editing the `requestlog.ini` and un-commenting the line that reads `jetty.requestlog.append=true`.
-____
-
+====
The equivalent code for embedded usages of Jetty is:
-[source, java, subs="{sub-order}"]
+[source, java]
----
NCSARequestLog requestLog = new NCSARequestLog("/var/logs/jetty/jetty-yyyy_mm_dd.request.log");
requestLog.setAppend(true);
@@ -120,7 +119,7 @@ Both timezones are set to GMT by default.
To configure a separate request log for specific a web application, add the following to the context XML file.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
...
diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/configuring-logging-modules.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/configuring-logging-modules.adoc
index 42cd6830f5cf..983cd3d36145 100644
--- a/jetty-documentation/src/main/asciidoc/administration/logging/configuring-logging-modules.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/logging/configuring-logging-modules.adoc
@@ -26,15 +26,15 @@ Please note that enabling these modules provides typical and basic functionality
Enabling these frameworks in the Jetty distribution is as easy as activating any other module, by adding `--add-to-start=` to the start command for your server, such as:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ../start.jar --add-to-start=logging-jetty
INFO : logging-jetty initialized in ${jetty.base}/start.d/logging-jetty.ini
INFO : resources transitively enabled
MKDIR : ${jetty.base}/resources
COPY : ${jetty.home}/modules/logging-jetty/resources/jetty-logging.properties to ${jetty.base}/resources/jetty-logging.properties
INFO : Base directory was modified
-....
+----
As noted above, Jetty supports a wide array of logging technologies.
If a particular logging framework requires additional jar files, Jetty will automatically download these as part of enabling the associated module and any dependent modules will be transitively enabled.
@@ -83,8 +83,8 @@ Jetty uses the SLF4J api as a binding to provide logging information to addition
It can also be used on it's own to provide simple server logging.
To enable the SLF4J framework, you need to activate the `logging-slf4j` module.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ../start.jar --add-to-start=logging-slf4j
ALERT: There are enabled module(s) with licenses.
@@ -126,14 +126,14 @@ ERROR : Unsatisfied module dependencies: logging-slf4j
Usage: java -jar $JETTY_HOME/start.jar [options] [properties] [configs]
java -jar $JETTY_HOME/start.jar --help # for more information
-....
+----
As you probably noticed, the system gives an `ERROR` when trying to enable the `logging-slf4j` on it's own.
The `logging-slf4j` module itself provides the SLF4J api, but as SLF4J is often used as a binding for other logging frameworks does not by default provide an implementation.
To enable the simple SLF4J implementation, we will also need to activate the `slf4j-simple-impl` module.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ../start.jar --add-to-start=slf4j-simple-impl
INFO : slf4j-simple-impl initialized in ${jetty.base}/start.d/slf4j-simple-impl.ini
INFO : resources transitively enabled
@@ -153,7 +153,7 @@ INFO : Base directory was modified
└── start.d
├── logging-slf4j.ini
└── slf4j-simple-impl.ini
-....
+----
Jetty is now configured to log using the SLF4J framework.
A standard SLF4J properties file is located in `${jetty.base}/resources/simplelogger.properties`.
@@ -165,8 +165,8 @@ It is possible to have the Jetty Server logging configured so that Log4j or Log4
This is accomplished by configuring Jetty for logging to http://logging.apache.org/log4j/[Apache Log4j] via http://slf4j.org/manual.html[Slf4j] and the http://slf4j.org/manual.html#swapping[Slf4j binding layer for Log4j].
Implementation of Log4j can be done by enabling the `logging-log4j` module.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ../start.jar --add-to-start=logging-log4j
ALERT: There are enabled module(s) with licenses.
@@ -227,15 +227,15 @@ INFO : Base directory was modified
│ └── log4j.xml
└── start.d
└── logging-log4j.ini
-....
+----
Jetty is now configured to log using the Log4j framework.
A standard Log4j configuration file is located in `${jetty.base}/resources/log4j.xml`.
Or, to set up Log4j2, enable the `logging-log4j2` module.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ../start.jar --add-to-start=logging-log4j2
ALERT: There are enabled module(s) with licenses.
@@ -299,7 +299,7 @@ INFO : Base directory was modified
│ └── log4j2.xml
└── start.d
└── logging-log4j2.ini
-....
+----
At this point Jetty is configured so that the Jetty server itself will log using Log4j2, using the Log4j2 configuration found in `{$jetty.base}/resources/log4j2.xml`.
@@ -311,8 +311,8 @@ This is accomplished by configuring Jetty for logging to `Logback`, which uses h
To set up Jetty logging via Logback, enable the `logging-logback` module.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ../start.jar --add-to-start=logging-logback
ALERT: There are enabled module(s) with licenses.
@@ -382,7 +382,7 @@ INFO : Base directory was modified
│ └── logback.xml
└── start.d
└── logging-logback.ini
-....
+----
At this point Jetty is configured so that the Jetty server itself will log using Logback, using the Logback configuration found in `{$jetty.base}/resources/logback.xml`.
@@ -394,8 +394,8 @@ It is possible to have the Jetty Server logging configured so that `java.util.lo
This example demonstrates how to configuring Jetty for logging to `java.util.logging` via http://slf4j.org/manual.html[SLF4J] as a binding layer.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ../start.jar --add-to-start=logging-jul
ALERT: There are enabled module(s) with licenses.
@@ -448,7 +448,7 @@ INFO : Base directory was modified
│ └── slf4j-jdk14-1.7.21.jar
└── start.d
└── logging-jul.ini
-....
+----
Jetty is now configured to log using the JUL framework.
A standard JUL properties file is located in `${jetty.base}/etc/java-util-logging.properties`.
@@ -459,8 +459,8 @@ By default, enabling the above modules will output log information to the consol
Included in the distribution is the `console-capture` module, which can be used in lieu of additional configuration to the selected logging module to capture this output to a `logs` directory in your `${jetty.base}`.
To enable this functionality, activate the `console-capture` module.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ../start.jar --add-to-start=console-capture
INFO : console-capture initialized in ${jetty.base}/start.d/console-capture.ini
MKDIR : ${jetty.base}/logs
@@ -471,24 +471,24 @@ INFO : Base directory was modified
├── logs
└── start.d
└── console-capture.ini
-....
+----
As an example, here is the output from Logback before using the `console-capture` module:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ../start.jar
419 [main] INFO org.eclipse.jetty.util.log - Logging initialized @508ms to org.eclipse.jetty.util.log.Slf4jLog
540 [main] INFO org.eclipse.jetty.server.Server - jetty-9.4.0-SNAPSHOT
575 [main] INFO o.e.jetty.server.AbstractConnector - Started ServerConnector@3c0ecd4b{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
575 [main] INFO org.eclipse.jetty.server.Server - Started @668ms
-....
+----
After enabling `console-capture`, the output is as follows, which displays the location the log is being saved to:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ../start.jar
151 [main] INFO org.eclipse.jetty.util.log - Logging initialized @238ms to org.eclipse.jetty.util.log.Slf4jLog
196 [main] INFO org.eclipse.jetty.util.log - Console stderr/stdout captured to /installs/jetty-distribution/mybase/logs/2016_10_21.jetty.log
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/default-logging-with-stderrlog.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/default-logging-with-stderrlog.adoc
index 7e2530285393..2f904a3135b9 100644
--- a/jetty-documentation/src/main/asciidoc/administration/logging/default-logging-with-stderrlog.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/logging/default-logging-with-stderrlog.adoc
@@ -31,8 +31,8 @@ Included in the Jetty distribution is a logging module named `console-capture` t
To enable this feature, simply activate the `console-capture` module on the command line:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ../start.jar --add-to-start=console-capture
INFO : console-capture initialized in ${jetty.base}/start.d/console-capture.ini
MKDIR : ${jetty.base}/logs
@@ -43,23 +43,21 @@ INFO : Base directory was modified
├── logs
└── start.d
└── console-capture.ini
-....
+----
The default configuration for logging output will create a file `${jetty.base}/logs/yyyy_mm_dd.stderrout.log` which allows configuration of the output directory by setting the `jetty.logs` property.
-____
[NOTE]
+====
By default, logs are not set to be appended, meaning a the log file is wiped clean upon sever restart.
You can change this setting by editing the `console-capture.ini` and un-commenting the line that reads `jetty.console-capture.append=true`.
-____
-
-
+====
Just enabling the `console-capture` will simply output the values of STDERR and STDOUT to a log file.
To customize the log further, a module named `logging-jetty` is available to provides a default properties file to configure.
As with `console-capture`, you activate the `logging-jetty` on the command line.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ../start.jar --add-to-start=logging-jetty
INFO : logging-jetty initialized in ${jetty.base}/start.d/logging-jetty.ini
INFO : resources transitively enabled
@@ -75,14 +73,14 @@ INFO : Base directory was modified
└── start.d
├── console-capture.ini
└── logging-jetty.ini
-....
+----
Once activated, you can find the properties file at `${jetty.base}/resources/jetty-logging.properties`.
By default, the following parameters are defined.
To change them, un-comment the line and substitute your naming scheme and configuration choices.
-[source, properties, subs="{sub-order}"]
-....
+[source, properties]
+----
## Force jetty logging implementation
#org.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StdErrLog
@@ -95,7 +93,7 @@ To change them, un-comment the line and substitute your naming scheme and config
## Show the source file of a log location?
#com.example.SOURCE=false
-....
+----
There are a number of properties that can be defined in the configuration that will affect the behavior of StdErr logging with `console-capture`.
@@ -125,23 +123,23 @@ There are a number of properties that can be defined in the configuration that w
+
* Example when set to false:
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
2016-10-21 15:31:01.248:INFO::main: Logging initialized @332ms to org.eclipse.jetty.util.log.StdErrLog
2016-10-21 15:31:01.370:INFO:oejs.Server:main: jetty-9.4.0-SNAPSHOT
2016-10-21 15:31:01.400:INFO:oejs.AbstractConnector:main: Started ServerConnector@2c330fbc{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2016-10-21 15:31:01.400:INFO:oejs.Server:main: Started @485ms
-....
+----
+
* Example when set to true:
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
2016-10-21 15:31:35.020:INFO::main: Logging initialized @340ms to org.eclipse.jetty.util.log.StdErrLog
2016-10-21 15:31:35.144:INFO:org.eclipse.jetty.server.Server:main: jetty-9.4.0-SNAPSHOT
2016-10-21 15:31:35.174:INFO:org.eclipse.jetty.server.AbstractConnector:main: Started ServerConnector@edf4efb{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2016-10-21 15:31:35.175:INFO:org.eclipse.jetty.server.Server:main: Started @495ms
-....
+----
[[deprecated-parameters]]
==== Deprecated Parameters
diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/example-apache-log4j.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/example-apache-log4j.adoc
index 5901c80c591b..52d8e3de1bae 100644
--- a/jetty-documentation/src/main/asciidoc/administration/logging/example-apache-log4j.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/logging/example-apache-log4j.adoc
@@ -23,8 +23,8 @@ This is accomplished by configuring Jetty for logging to http://logging.apache.o
A convenient replacement `logging` module has been created to bootstrap your `${jetty.base}` directory for logging with log4j.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase]$ mkdir modules
[mybase]$ cd modules
@@ -46,7 +46,7 @@ INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/start.ini
[mybase]$ java -jar /opt/jetty-dist/start.jar
-....
+----
The replacement `logging.mod` performs a number of tasks.
diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging-native.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging-native.adoc
index 0169b30736b3..b134472af9e5 100644
--- a/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging-native.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging-native.adoc
@@ -25,16 +25,15 @@ Jetty.
This example demonstrates how to configuring Jetty for logging to
`java.util.logging` via Jetty's own JavaUtilLog implementation.
-____
[IMPORTANT]
+====
While this is a valid setup, the Jetty project recommends always using the link:#example-logging-java-util-logging[slf4j to java.util.logging configuration] for memory and performance reasons.
This native implementation is very non-performant and is not guaranteed to exist in the future.
-____
-
+====
A convenient replacement `logging` module has been created to bootstrap your `${jetty.base}` directory for logging with `java.util.logging`.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase]$ mkdir modules
[mybase]$ cd modules
@@ -54,7 +53,7 @@ INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/${jetty.base}
[mybase]$ java -jar /opt/jetty-dist/start.jar
-....
+----
The replacement `logging.mod` performs a number of tasks.
@@ -78,8 +77,8 @@ In essence, Jetty is now configured to use `org.eclipse.jetty.util.log.JavaUtilL
If there any custom `java.util.logging` handlers to be used, put the implementation jar in the `${jetty.base}/lib/logging/` directory and reference them in the `${jetty.base}/resources/logging.properties` file.
-____
[NOTE]
+====
`java.util.logging` is configured via the `${jetty.base}/resources/logging.properties` file during a valid startup of Jetty.
This means that if there is any startup errors that occur before `java.util.logging` is configured, they will likely be lost and/or not routed through your configuration.
@@ -88,4 +87,4 @@ Other logging frameworks are more reliable in that they always initialize and co
* While it is possible to configure `java.util.logging` sooner, even at JVM startup, the example demonstrated here does not show this technique.
For more information consult the official `java.util.logging.LogManager` javadoc http://docs.oracle.com/javase/7/docs/api/java/util/logging/LogManager.html[documentation from Oracle].
-____
+====
diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging.adoc
index d11e6d720773..72c099c4a71b 100644
--- a/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging.adoc
@@ -25,8 +25,8 @@ If you want to use the built-in native `JavaUtilLog` implementation, see #exampl
A convenient replacement `logging` module has been created to bootstrap your `${jetty.base}` directory for logging with `java.util.logging`.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase]$ mkdir modules
[mybase]$ cd modules
@@ -48,7 +48,7 @@ INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/start.ini
[mybase]$ java -jar /opt/jetty-dist/start.jar
-....
+----
The replacement `logging.mod` performs a number of tasks.
@@ -73,8 +73,8 @@ In essence, Jetty is now configured to emit its own logging events to slf4j, and
If there any custom `java.util.logging` handlers to be used, put the implementation jar in the `${jetty.base}/lib/logging/` directory and reference them in the `${jetty.base}/resources/logging.properties` file.
-____
[NOTE]
+====
`java.util.logging` is configured via the `${jetty.base}/resources/logging.properties` file during a valid startup of Jetty.
This means that if there is any startup errors that occur before `java.util.logging` is configured, they will likely be lost and/or not routed through your configuration.
@@ -83,4 +83,4 @@ Other logging frameworks are more reliable in that they always initialize and co
* While it is possible to configure `java.util.logging` sooner, even at JVM startup, the example demonstrated here does not show this technique.
For more information consult the official `java.util.logging.LogManager` javadoc http://docs.oracle.com/javase/7/docs/api/java/util/logging/LogManager.html[documentation from Oracle].
-____
+====
diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/example-logback-centralized-logging.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/example-logback-centralized-logging.adoc
index ef5e328d00ba..b27c314fd461 100644
--- a/jetty-documentation/src/main/asciidoc/administration/logging/example-logback-centralized-logging.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/logging/example-logback-centralized-logging.adoc
@@ -24,12 +24,11 @@ It routes all logging events from the web applications to a single configuration
The example below shows how to accomplish this with Jetty and Slf4j, using `Logback` to manage the final writing of logs to disk.
-____
[IMPORTANT]
+====
This mechanism forces all webapps to use the server's configuration for logging, something that isn't 100% appropriate for all webapps.
An example would be having Jenkins-CI deployed as an webapp, if you force its logging configuration to the server side, you lose the ability on http://jenkins-ci.org/[Jenkins-CI] to see the logs from the various builds (as now those logs are actually going to the main server log).
-____
-
+====
This configuration is essentially the multiple logger configuration with added configuration to the deployers to force a `WebAppClassLoader` change to use the server classpath over the webapps classpath for the logger specific classes.
The technique used by this configuration is to provide an link:{JDURL}org/eclipse/jetty/deploy/AppLifeCycle.Binding.html[AppLifeCycle.Binding] against the link:{JDURL}/org/eclipse/jetty/deploy/AppLifeCycle.html[`"deploying"`node] that modifies the
@@ -38,8 +37,8 @@ See https://github.com/jetty-project/jetty-webapp-logging/blob/master/jetty-weba
A convenient replacement `logging` module has been created to bootstrap your `${jetty.base}` directory for capturing all Jetty server logging from multiple logging frameworks into a single logging output file managed by Logback.
-[source,screen,subs="{sub-order}"]
-....
+[source,screen,]
+----
[mybase]$ curl -O https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-webapp-logging/9.4.27/jetty-webapp-logging-9.4.27-config.jar
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
@@ -114,7 +113,7 @@ DOWNLD: https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-webapp-logging/9.
INFO : Base directory was modified
$
-....
+----
This replacement `centralized-webapp-logging.mod` performs a number of tasks.
diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/example-logback-sifting.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/example-logback-sifting.adoc
index a93a17808f97..8979e827e68e 100644
--- a/jetty-documentation/src/main/asciidoc/administration/logging/example-logback-sifting.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/logging/example-logback-sifting.adoc
@@ -23,9 +23,9 @@ This page describes how to create log files at the server level and name them ba
This can be done with SLF4J + Logback + Jetty Webapp Logging in the mix.
Find example projects for this feature at github:
-....
+----
https://github.com/jetty-project/jetty-and-logback-example
-....
+----
.GitHub Example Project
[cols=",",options="header",]
diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/example-logback.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/example-logback.adoc
index f570ab496fc0..f4a683d486ec 100644
--- a/jetty-documentation/src/main/asciidoc/administration/logging/example-logback.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/logging/example-logback.adoc
@@ -23,8 +23,8 @@ This is accomplished by configuring Jetty for logging to `Logback`, which uses h
A convenient replacement `logging` module has been created to bootstrap the `${jetty.base}` directory for logging with logback.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase]$ mkdir modules
[mybase]$ cd modules
@@ -44,7 +44,7 @@ DOWNLOAD: https://raw.githubusercontent.com/jetty-project/logging-modules/master
DOWNLOAD: https://raw.githubusercontent.com/jetty-project/logging-modules/master/logback/jetty-logging.properties to resources/jetty-logging.properties
[mybase]$ java -jar /opt/jetty-dist/start.jar
-....
+----
The replacement `logging.mod` performs a number of tasks.
diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/example-slf4j-multiple-loggers.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/example-slf4j-multiple-loggers.adoc
index b657d63ec748..7e2b52919c61 100644
--- a/jetty-documentation/src/main/asciidoc/administration/logging/example-slf4j-multiple-loggers.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/logging/example-slf4j-multiple-loggers.adoc
@@ -34,19 +34,17 @@ Logging APIs that Slf4j supports:
To accomplish this configuration a single underlying logging framework should first be chosen.
This decision guides the rest of the choices about jar files to place on the server classpath.
-____
[CAUTION]
+====
There MUST NOT be multiple underlying logging frameworks on the classpath.
If there are, the Slf4j framework fails to load.
-____
-
-____
+====
[NOTE]
+====
Some third party libraries provide their own implementations of common logging APIs; be careful not to accidentally include an underlying logging framework.
For example, if you are using SpringSource you likely have a `com.springsource.org.apache.log4j.jar` along with a `log4j.jar`, which have the same classes in them.
In this example, use the `com.springsource.org.apache.log4j.jar` version and exclude the `log4j.jar`, as the SpringSource version includes extra metadata suitable for using SpringSource.
-____
-
+====
.Slf4j Logging Grid
[width="100%",cols="25%,25%,25%,25%",options="header",]
|=======================================================================
@@ -88,8 +86,8 @@ It also requires including the other Slf4j binding JARs in the classpath, along
A convenient replacement `logging` module has been created to bootstrap the `${jetty.base}` directory for capturing all Jetty server logging from multiple logging frameworks into a single logging output file managed by logback.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase]$ mkdir modules
[mybase]$ cd modules
@@ -115,7 +113,7 @@ INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/start.ini
[mybase]$ java -jar /opt/jetty-dist/start.jar
-....
+----
The replacement `logging.mod` performs a number of tasks.
diff --git a/jetty-documentation/src/main/asciidoc/administration/logging/jetty-server-dump.adoc b/jetty-documentation/src/main/asciidoc/administration/logging/jetty-server-dump.adoc
index e6e3777b11a4..8542d55ac1ad 100644
--- a/jetty-documentation/src/main/asciidoc/administration/logging/jetty-server-dump.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/logging/jetty-server-dump.adoc
@@ -79,7 +79,7 @@ The Server MBean has a `dump()` method, which dumps everything, plus a `dumpStdE
This is a dump of the OneServletContext embedded example with extra threadpool information:
-....
+----
Server@59906517{STARTED}[9.4.32-SNAPSHOT] - STARTED
+= QueuedThreadPool[qtp488044861]@1d16f93d{STARTED,8<=8<=200,i=2,r=4,q=0}[ReservedThreadExecutor@16267862{s=2/4,p=0}] - STARTED
| += ReservedThreadExecutor@16267862{s=2/4,p=0} - STARTED
@@ -221,4 +221,4 @@ Server@59906517{STARTED}[9.4.32-SNAPSHOT] - STARTED
+> jdk.internal.loader.ClassLoaders$AppClassLoader@2c13da15
+> jdk.internal.loader.ClassLoaders$PlatformClassLoader@7364985f
key: +- bean, += managed, +~ unmanaged, +? auto, +: iterable, +] array, +@ map, +> undefined
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/part.adoc b/jetty-documentation/src/main/asciidoc/administration/part.adoc
index fa22eaeb091e..a47edce2f1d9 100644
--- a/jetty-documentation/src/main/asciidoc/administration/part.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/part.adoc
@@ -18,7 +18,7 @@
[[jetty-admin-guide]]
-= Jetty Administration Guide
+== Jetty Administration Guide
include::startup/chapter.adoc[]
include::sessions/chapter.adoc[]
diff --git a/jetty-documentation/src/main/asciidoc/administration/runner/jetty-runner.adoc b/jetty-documentation/src/main/asciidoc/administration/runner/jetty-runner.adoc
index 0cab866c2708..4672c3da03ff 100644
--- a/jetty-documentation/src/main/asciidoc/administration/runner/jetty-runner.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/runner/jetty-runner.adoc
@@ -34,33 +34,32 @@ You will need the `jetty-runner` jar:
Let's assume we have a very simple webapp that does not need any resources from its environment, nor any configuration apart from the defaults.
Starting it is as simple as performing the following:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar simple.war
-....
+----
This will start Jetty on port 8080, and deploy the webapp to `/`.
Your webapp does not have to be packed into a war, you can deploy a webapp that is a directory instead in the same way:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar simple
-....
+----
In fact, the webapp does not have to be a war or even a directory, it can simply be a Jetty link:#using-context-provider[context xml] file that describes your webapp:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar simple-context.xml
-....
+----
-____
[NOTE]
+====
When using a context xml file, the application being deployed is not even required to be a fully-fledged webapp.
It can simply be a Jetty link:#what-is-a-context[context].
-____
-
+====
By default, `jetty-runner` implements all Configuration Classes so that users can set up and deploy new instances with as little configuration as possible.
If you wish to only implement certain Configuration Classes, they will need to be defined in the context xml for the webapp/context.
The default Configuration Classes are:
@@ -82,60 +81,58 @@ If you have more than one webapp that must be deployed, simply provide them all
You can control the context paths for them using the `--path` parameter.
Here's an example of deploying 2 wars (although either or both of them could be unpacked directories instead):
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --path /one my1.war --path /two my2.war
-....
+----
If you have context xml files that describe your webapps, you can fully configure your webapps in them and hence you won't need to use the command line switches.
Just provide the list of context files like so:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar my-first-context.xml my-second-context.xml my-third-context.xml
-....
+----
-____
[NOTE]
+====
Switched used on the command line override configuration file settings.
So, for example, you could set the context path for the webapp inside the context xml file, and use the `--path` switch to override it on the command line.
-____
-
-
+====
===== Changing the Default Port
By default the `jetty-runner` will listen on port 8080.
You can easily change this on the command line using the `--port` command.
Here's an example that runs our simple.war on port 9090:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --port 9090 simple.war
-....
+----
===== Using jetty.xml Files
Instead of, or in addition to, using command line switches, you can use one or more `jetty.xml` files to configure the environment for your webapps.
Here's an example where we apply two different `jetty.xml` files:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --config jetty.xml --config jetty-https.xml simple.war
-....
+----
[[runner-configuration-reference]]
==== Full Configuration Reference
You can see the fill set of configuration options using the `--help` switch:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --help
-....
+----
Here's what the output will look like:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
Usage: java [-Djetty.home=dir] -jar jetty-runner.jar [--help|--version] [ server opts] [[ context opts] context ...]
@@ -159,66 +156,66 @@ Context opts:
===== Printing the Version
Print out the version of Jetty and then exit immediately.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --version
-....
+----
===== Configuring a Request Log
Cause Jetty to write a request log with the given name.
If the file is prefixed with `yyyy_mm_dd` then the file will be automatically rolled over.
Note that for finer grained configuration of the link:{JDURL}/org/eclipse/jetty/server/NCSARequestLog.html[request log], you will need to use a Jetty xml file instead.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --log yyyy_mm_dd-requests.log my.war
-....
+----
===== Configuring the Output Log
Redirect the output of jetty logging to the named file.
If the file is prefixed with `yyyy_mm_dd` then the file will be automatically rolled over.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --out yyyy_mm_dd-output.log my.war
-....
+----
===== Configuring the Interface for HTTP
Like Jetty standalone, the default is for the connectors to listen on all interfaces on a machine.
You can control that by specifying the name or ip address of the particular interface you wish to use with the `--host` argument:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --host 192.168.22.19 my.war
-....
+----
===== Configuring the Port for HTTP
The default port number is 8080.
To link:#how-to-configure-connectors[configure a https connector], use a Jetty xml config file instead.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --port 9090 my.war
-....
+----
===== Configuring Stop
You can configure a port number for Jetty to listen on for a stop command, so you are able to stop it from a different terminal.
This requires the use of a "secret" key, to prevent malicious or accidental termination.
Use the `--stop-port` and `--stop-key` (or `-DSTOP.PORT=` and `-DSTOP.KEY=`, respectively) parameters as arguments to the `jetty-runner`:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --stop-port 8181 --stop-key abc123
-....
+----
Then, to stop Jetty from a different terminal, you need to supply the same port and key information.
For this you'll either need a local installation of Jetty, the link:#jetty-maven-plugin[jetty-maven-plugin], the link:#jetty-ant[jetty-ant plugin], or a custom class.
Here's how to use a Jetty installation to perform a stop:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar start.jar -DSTOP.PORT=8181 -DSTOP.KEY=abc123 --stop
-....
+----
===== Configuring the Container Classpath
With a local installation of Jetty, you add jars and classes to the container's classpath by putting them in the `{$jetty.base}/lib` directory.
@@ -228,52 +225,50 @@ With the `jetty-runner`, you can use the `--lib`, `--jar` and `--classes` argume
You can add 1 or more.
Here's an example of configuring 2 directories:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --lib /usr/local/external/lib --lib $HOME/external-other/lib my.war
-....
+----
`--jar` adds a single jar file to the container classpath.
You can add 1 or more.
Here's an example of configuring 3 extra jars:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --jar /opt/stuff/jars/jar1.jar --jar $HOME/jars/jar2.jar --jar /usr/local/proj/jars/jar3.jar my.war
-....
+----
`--classes` add the location of a directory containing classes to add to the container classpath.
You can add 1 or more.
Here's an example of configuring a single extra classes dir:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --classes /opt/stuff/classes my.war
-....
+----
-____
[NOTE]
+====
When using the `--jar` and/or `--lib` arguments, by default these will *not* be inspected for `META-INF` information such as `META-INF/resources`, `META-INF/web-fragment.xml`, or `META-INF/taglib.tld`.
If you require these jar files inspected you will need to define the link:https://www.eclipse.org/jetty/documentation/current/configuring-webapps.html#webapp-context-attributes[jar pattern in your context xml file].
Jetty-Runner automatically provides and appends a suitable pattern for jtsl taglibs (this pattern is different than the one in the standard Jetty distribution).
-____
-
-
+====
===== Gathering Statistics
If statistics gathering is enabled, then they are viewable by surfing to the context `/stats`.
You may optionally protect access to that context with a password.
Here's an example of enabling statistics, with no password protection:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --stats unsecure my.war
-....
+----
If we wished to protect access to the `/stats` context, we would provide the location of a Jetty realm configuration file containing authentication and authorization information.
For example, we could use the following example realm file from the Jetty distribution:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
jetty: MD5:164c88b302622e17050af52c89945d44,user
admin: CRYPT:adpexzg3FUZAk,server-administrator,content-administrator,admin
other: OBF:1xmk1w261u9r1w1c1xmq,user
@@ -281,18 +276,18 @@ plain: plain,user
user: password,user
# This entry is for digest auth. The credential is a MD5 hash of username:realmname:password
digest: MD5:6e120743ad67abfbc385bc2bb754e297,user
-....
+----
Assuming we've copied it into the local directory, we would apply it like so
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar jetty-runner.jar --stats realm.properties my.war
-....
+----
After navigating to http://localhost:8080/ a few times, we can point to the stats servlet on http://localhost:8080/stats to see the output:
-....
+----
Statistics:
Statistics gathering started 1490627ms ago
@@ -346,4 +341,4 @@ Total messages out: 7
Memory:
Heap memory usage: 49194840 bytes
Non-heap memory usage: 12611696 bytes
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-gcloud-datastore.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-gcloud-datastore.adoc
index 9f45385ed7ee..c097718697dd 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-gcloud-datastore.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-gcloud-datastore.adoc
@@ -50,7 +50,7 @@ To do that, you can use `--skip-file-validation=glcoud-sessions` argument to sta
The gcloud-sessions module will have installed file called `${jetty.home}/etc/jetty-gcloud-sessions.xml`.
This file configures an instance of the `GCloudSessionIdManager` that will be shared across all webapps deployed on that server. It looks like this:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/jetty-gcloud/jetty-gcloud-session-manager/src/main/config/etc/jetty-gcloud-sessions.xml[]
----
@@ -105,7 +105,7 @@ The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.
From a context xml file, you reference the Server instance as a Ref:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
[
@@ -129,7 +129,7 @@ From a context xml file, you reference the Server instance as a Ref:
From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -202,7 +202,7 @@ The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.
From a context xml file, you reference the Server instance as a Ref:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
][
@@ -229,7 +229,7 @@ From a context xml file, you reference the Server instance as a Ref:
From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-infinispan.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-infinispan.adoc
index d7b5f09e35fa..e0d3eebb3d51 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-infinispan.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-infinispan.adoc
@@ -47,10 +47,10 @@ To do that, you can use `--skip-file-validation=infinispan` argument to start.ja
You will also find the following properties, either in your base's `start.d/infinispan.ini` file or appended to your `start.ini`, depending on how you enabled the module:
-....
+----
## Unique identifier for this node in the cluster
jetty.infinispanSession.workerName=node1
-....
+----
jetty.infinispanSession.workerName::
The name that uniquely identifies this node in the cluster.
@@ -65,7 +65,7 @@ The Infinispan module will have installed file called `$\{jetty.home}/etc/jetty-
This file configures an instance of the `InfinispanSessionIdManager` that will be shared across all webapps deployed on that server.
It looks like this:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/jetty-infinispan/src/main/config/etc/jetty-infinispan.xml[]
----
@@ -91,7 +91,7 @@ The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.
From a context xml file, you reference the Server instance as a Ref:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -132,7 +132,7 @@ From a context xml file, you reference the Server instance as a Ref:
From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -187,6 +187,6 @@ To do this, firstly ensure that you have included the lines containing the `getS
Then, create the file `${jetty.base}/resources/hotrod-client.properties`.
Add the following line to this file:
-....
+----
infinispan.client.hotrod.marshaller=org.eclipse.jetty.session.infinispan.WebAppMarshaller
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-jdbc.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-jdbc.adoc
index faf912e2bc0b..96bd32150862 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-jdbc.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-jdbc.adoc
@@ -46,7 +46,7 @@ When using the jetty distribution, to enable jdbc session persistence, you will
You will also find the following properties, either in your base's start.d/jdbc-session.ini file or appended to your start.ini, depending on how you enabled the module:
-[source, java, subs="{sub-order}"]
+[source, java]
----
## Unique identifier for this node in the cluster
jetty.jdbcSession.workerName=node1
@@ -80,7 +80,7 @@ The jdbc-session module will have installed file called `$\{jetty.home}/etc/jett
This file configures an instance of the `JDBCSessionIdManager` that will be shared across all webapps deployed on that server.
It looks like this:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/jetty-server/src/main/config/etc/jetty-jdbc-sessions.xml[]
----
@@ -89,7 +89,7 @@ As well as uncommenting and setting up appropriate values for the properties dis
As Jetty configuration files are direct mappings of XML to Java, it is straight forward to do this in code:
-[source, java, subs="{sub-order}"]
+[source, java]
----
Server server = new Server();
...
@@ -129,7 +129,7 @@ These classes have getter/setter methods for the table name and all columns.
Here's an example of changing the name of `JettySessionsId` table and its single column.
This example will use java code, but as explained above, you may also do this via a Jetty xml configuration file:
-[source, java, subs="{sub-order}"]
+[source, java]
----
JDBCSessionIdManager idManager = new JDBCSessionIdManager(server);
@@ -142,7 +142,7 @@ idManager.setSessionIdTableSchema(idTableSchema);
In a similar fashion, you can change the names of the table and columns for the `JettySessions` table.
*Note* that both the `SessionIdTableSchema` and the `SessionTableSchema` instances are set on the `JDBCSessionIdManager` class.
-[source, java, subs="{sub-order}"]
+[source, java]
----
JDBCSessionIdManager idManager = new JDBCSessionIdManager(server);
@@ -172,7 +172,7 @@ The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.
From a context xml file, you reference the Server instance as a Ref:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
][
@@ -192,7 +192,7 @@ From a context xml file, you reference the Server instance as a Ref:
From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -213,7 +213,7 @@ From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance direc
If you're embedding this in code:
-[source, java, subs="{sub-order}"]
+[source, java]
----
//assuming you have already set up the JDBCSessionIdManager as shown earlier
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-mongodb.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-mongodb.adoc
index 658a55f484f6..ef8d7b661621 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-mongodb.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-mongodb.adoc
@@ -53,7 +53,7 @@ To do that, you can use `--skip-file-validation=nosql` argument to start.jar on
You will also find the following properties, either in your base's `start.d/nosql.ini` file or appended to your `start.ini`, depending on how you enabled the module:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
## Unique identifier for this node in the cluster
jetty.nosqlSession.workerName=node1
@@ -77,7 +77,7 @@ The nosql module will have installed file called `$\{jetty.home}/etc/jetty-nosql
This file configures an instance of the `MongoSessionIdManager` that will be shared across all webapps deployed on that server.
It looks like this:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/jetty-nosql/src/main/config/etc/jetty-nosql.xml[]
----
@@ -86,7 +86,7 @@ The `MongoSessionIdManager` needs access to a MongoDB cluster, and the `jetty-no
If you need to configure something else, you will need to edit this file.
Here's an example of a more complex setup to use a remote MongoDB instance:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -130,7 +130,7 @@ Here's an example of a more complex setup to use a remote MongoDB instance:
As Jetty configuration files are direct mappings of XML to Java, it is straight forward to do this in code:
-[source, java, subs="{sub-order}"]
+[source, java]
----
Server server = new Server();
@@ -186,7 +186,7 @@ The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.
From a context xml file, you reference the Server instance as a Ref:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
][
@@ -207,7 +207,7 @@ From a context xml file, you reference the Server instance as a Ref:
From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -227,7 +227,7 @@ From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance direc
If you're embedding this in code:
-[source, java, subs="{sub-order}"]
+[source, java]
----
//assuming you have already set up the MongoSessionIdManager as shown earlier
//and have a reference to the Server instance:
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/setting-session-characteristics.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/setting-session-characteristics.adoc
index 095ee8db5851..fb1d562f7c5c 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/setting-session-characteristics.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/legacy/setting-session-characteristics.adoc
@@ -74,7 +74,7 @@ The following sections provide examples of how to apply the init parameters.
You can set these parameters as context parameters in a web application's `WEB-INF/web.xml` file:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -103,7 +103,7 @@ You can set these parameters as context parameters in a web application's `WEB-I
You can configure init parameters on a web application, either in code, or in a Jetty context xml file equivalent:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -130,7 +130,7 @@ You can configure init parameters on a web application, either in code, or in a
You can configure init parameters directly on a `SessionManager` instance, either in code or the equivalent in xml:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -165,7 +165,7 @@ For full details, consult the http://docs.oracle.com/javaee/6/api/javax/servlet/
Below is an example of this implementation: a `ServletContextListener` retrieves the `SessionCookieConfig` and sets up some new values when the context is being initialized:
-[source, java, subs="{sub-order}"]
+[source, java]
----
import javax.servlet.SessionCookieConfig;
import javax.servlet.ServletContextEvent;
@@ -205,7 +205,7 @@ public class TestListener implements ServletContextListener
You can also use `web.xml` to configure the session handling characteristics instead: here's an example doing exactly the same as above instead of using code:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
);
----
You may also set the tracking mode in `web.xml`, e.g.:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -75,7 +75,7 @@ For example, the Wicket web framework requires the servlet environment to be ava
Using `SessionManager.setLazyLoad(true)`, Jetty loads sessions lazily either when it receives the first request for a session, or the session scavenger runs for the first time, whichever happens first.
Here's how the configuration looks in XML:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -93,7 +93,7 @@ Here's how the configuration looks in XML:
To enable session persistence for the Jetty Maven plugin, set up the `HashSessionManager` in the configuration section like so:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-file-system.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-file-system.adoc
index 3b5eea4c2154..3fe21cfbd057 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-file-system.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-file-system.adoc
@@ -26,7 +26,7 @@ Note: Persisting sessions to the local file system should *not* be used in a clu
When using the Jetty distribution, you will first need to enable the `session-store-file` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
@@ -48,17 +48,16 @@ By default Session files will be saved to this directory.
In addition to adding these modules to the classpath of the server, several ini configuration files were added to the `${jetty.base}/start.d` directory.
-____
[NOTE]
+====
Session data is now only loaded when requested.
Previous functionality such as `setLazyLoad` has been removed.
-____
-
+====
==== Configuring File System Session Properties
Opening `start.d/session-store-file.ini` will show a list of all the configurable options for the file system session module:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# ---------------------------------------
# Module: session-store-file
@@ -80,10 +79,10 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
-____
[NOTE]
+====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
-____
+====
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-gcloud.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-gcloud.adoc
index ede40efe8752..9943576ab3d3 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-gcloud.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-gcloud.adoc
@@ -66,7 +66,7 @@ To enable communication using the GCloud Emulator:
When using the Jetty distribution, you will first need to enable the `session-store-gcloud` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
@@ -191,7 +191,7 @@ It does *not*, however, configure a SLF4J implementation for the users.
As such, you will also need to enable one of the SLF4J implementation modules listed.
In this example, we will enable the `slf4j-simple-impl` module to provide a SLF4J implementation.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ java -jar ../start.jar --add-to-start=slf4j-simple-impl
INFO : slf4j-simple-impl initialized in ${jetty.base}/start.d/slf4j-simple-impl.ini
@@ -206,16 +206,15 @@ When the `--add-to-start` argument was added to the command line the first time,
In addition to adding these modules to the classpath of the server it also added the respective configuration files to the `${jetty.base}start.d` directory.
-____
[NOTE]
+====
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=` command line option to prevent errors when starting your server.
-____
-
+====
==== Configuring GCloud Session Properties
Opening the `start.d/session-store-gcloud.ini` will display a list of all the configurable properties for the Google Cloud DataStore module:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# ---------------------------------------
# Module: session-store-gcloud
@@ -250,14 +249,13 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
-____
[NOTE]
+====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
-____
-
+====
jetty.session.gcloud.maxRetries::
Maxmium number of tries to connect to GCloud DataStore to write sessions.
jetty.session.gcloud.backoffMs::
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-hazelcast.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-hazelcast.adoc
index ce252b048335..f53fff3dd74d 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-hazelcast.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-hazelcast.adoc
@@ -24,7 +24,7 @@
When using the Jetty distribution, you will first need to enable the `session-store-hazelcast-remote` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ java -jar ../start.jar --create-startd
MKDIR : ${jetty.base}/start.d
@@ -64,16 +64,15 @@ It also downloaded the needed Hazelcast-specific jar files and created a directo
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `${jetty.base}/start.d` directory.
-____
[NOTE]
+====
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=` command line option to prevent errors when starting your server.
-____
-
+====
==== Configuring Hazelcast Remote Properties
Opening the `start.d/session-store-hazelcast-remote.ini` will show a list of all the configurable options for the Hazelcast module:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# ---------------------------------------
# Module: session-store-hazelcast-remote
@@ -103,22 +102,21 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
-____
[NOTE]
+====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
Be aware using the `scavengeZombies` option that if your session attributes contain classes from inside your webapp (or jetty classes) then you will need to put these classes onto the classpath of all of your hazelcast instances.
-____
-
+====
==== Configuring Embedded Hazelcast Clustering
During testing, it can be helpful to run an in-process instance of Hazelcast.
To enable this you will first need to enable the `session-store-hazelcast-embedded` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ java -jar ../start.jar --create-startd
MKDIR : ${jetty.base}/start.d
@@ -160,7 +158,7 @@ In addition to adding these modules to the classpath of the server it also added
Opening the `start.d/start.d/session-store-hazelcast-embedded.ini` will show a list of all the configurable options for the Hazelcast module:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# ---------------------------------------
# Module: session-store-hazelcast-embedded
@@ -186,12 +184,12 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
-____
[NOTE]
+====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
Be aware using the `scavengeZombies` option that if your session attributes contain classes from inside your webapp (or jetty classes) then you will need to put these classes onto the classpath of all of your hazelcast instances. In the cast of embedded hazelcast, as it is started before your webapp, it will NOT have access to your webapp's classes - you will need to extract these classes and put them onto the jetty server's classpath.
-____
+====
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-infinispan.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-infinispan.adoc
index 1070b6db70de..47c039325212 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-infinispan.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-infinispan.adoc
@@ -25,7 +25,7 @@
When using the Jetty distribution, you will first need to enable the `session-store-infinispan-remote` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
@@ -63,16 +63,15 @@ It also downloaded the needed Infinispan-specific jar files and created a direct
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `${jetty.base}/start.d` directory.
-____
[NOTE]
+====
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=` command line option to prevent errors when starting your server.
-____
-
+====
==== Configuring Inifinspan Remote Properties
Opening the `start.d/session-store-infinispan-remote.ini` will show a list of all the configurable options for the JDBC module:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# ---------------------------------------
# Module: session-store-infinispan-remote
@@ -100,20 +99,19 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
-____
[NOTE]
+====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
-____
-
+====
==== Configuring the Remote Infinispan Query Module
Enabling this module allows jetty to search infinispan for expired sessions that are no longer being referenced by any jetty node.
Note that this is an *additional* module, to be used in conjuction with the `session-store-infinispan-remote` module.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
java -jar ../start.jar --add-to-start=infinispan-remote-query
----
@@ -126,12 +124,11 @@ There are no configuration properties associated with this module.
During testing, it can be helpful to run an in-process instance of Infinispan.
To enable this you will first need to enable the `session-store-infinispan-embedded` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
-____
[IMPORTANT]
+====
If you are running Jetty with JDK 9 or greater, enable `session-store-infinispan-embedded-910.mod` instead.
-____
-
-[source, screen, subs="{sub-order}"]
+====
+[source, screen]
----
java -jar ../start.jar --add-to-start=session-store-infinispan-embedded
@@ -167,7 +164,7 @@ In addition to adding these modules to the classpath of the server it also added
Opening the `start.d/session-store-infinispan-remote.ini` will show a list of all the configurable options for the JDBC module:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# ---------------------------------------
# Module: session-store-infinispan-embedded
@@ -185,20 +182,18 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
-____
[NOTE]
+====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
-____
-
-
+====
==== Configuring Inifinspan Embedded Query
Similarly to the `session-store-infinispan-remote` module, the `session-store-infinispan-embedded` module has an adjunct module `infinispan-embedded-query`, which when enabled, will allow jetty to detect and properly scavenge defunct sessions stranded in infinispan.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
java -jar ../start.jar --add-to-start=infinispan-embedded-query
----
@@ -213,14 +208,13 @@ Prior to release 9.4.13 we used the default Infinispan serialization, however th
See issue https://github.com/eclipse/jetty.project/issues/2919 for more background.
We have provided a conversion program which will convert any sessions stored in Infinispan to the new format.
-____
[IMPORTANT]
+====
We recommend that you backup your stored sessions before running the conversion program.
-____
-
+====
How to use the converter:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
java -cp servlet-api-3.1.jar:jetty-util-9.4.13.jar:jetty-server-9.4.13.jar:infinispan-remote-9.1.0.Final.jar:jetty-infinispan-9.4.13.jar:[other classpath] org.eclipse.jetty.session.infinispan.InfinispanSessionLegacyConverter
@@ -240,7 +234,7 @@ When used with no arguments the usage message is printed. When used with the `ca
To perform the conversion, run the InfinispanSessionLegacyConverter with just the `cache-name`, and optionally the `host` system property.
The following command will attempt to convert all sessions in the cached named `my-remote-cache` on the machine `myhost`, ensuring that application classes in the `/my/custom/classes` directory are on the classpath:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
java -cp servlet-api-3.1.jar:jetty-util-9.4.13.jar:jetty-server-9.4.13.jar:infinispan-remote-9.1.0.Final.jar:jetty-infinispan-9.4.13.jar:/my/custom/classes org.eclipse.jetty.session.infinispan.InfinispanSessionLegacyConverter -Dhost=myhost my-remote-cache
----
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-jdbc.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-jdbc.adoc
index 533cc88e0611..5f0091ed938a 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-jdbc.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-jdbc.adoc
@@ -24,7 +24,7 @@
When using the Jetty distribution, you will first need to enable the `session-store-jdbc` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
@@ -48,7 +48,7 @@ In addition to adding these modules to the classpath of the server, several ini
Opening the `start.d/session-store-jdbc.ini` will show a list of all the configurable options for the JDBC module:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# ---------------------------------------
# Module: session-store-jdbc
@@ -103,14 +103,13 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
-____
[NOTE]
+====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
-____
-
+====
db-connection-type::
Set to either `datasource` or `driver` depending on the type of connection being used.
jetty.session.jdbc.datasourceName::
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-memcachedsessiondatastore.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-memcachedsessiondatastore.adoc
index dd4750fc7454..e7e09d6a2775 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-memcachedsessiondatastore.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-memcachedsessiondatastore.adoc
@@ -31,7 +31,7 @@ To enable it with the Jetty distribution, enable the `session-store-cache` link:
After enabling, the `$jetty.base/start.d/session-store-cache.ini` file will be generated:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
--module=session-store-cache
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-mongodb.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-mongodb.adoc
index bc56d0818688..d475a6e1e813 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-mongodb.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-mongodb.adoc
@@ -24,7 +24,7 @@
When using the Jetty distribution, you will first need to enable the `session-store-mongo` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
@@ -61,16 +61,15 @@ It also downloaded the needed Mongo-specific jar file and created a directory na
In addition to adding these modules to the classpath of the server, several ini configuration files were added to the `${jetty.base}/start.d` directory.
-____
[NOTE]
+====
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=` command line option to prevent errors when starting your server.
-____
-
+====
==== Configuring MongoDB Session Properties
Opening the `start.d/session-store-mongo.ini` will show a list of all the configurable options for the MongoDB module:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# ---------------------------------------
# Module: session-store-mongo
@@ -97,14 +96,13 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
-____
[NOTE]
+====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
-____
-
+====
jetty.session.mongo.dbName::
Name of the database in Mongo used to store the Session collection.
jetty.session.mongo.collectionName::
@@ -123,9 +121,9 @@ jetty.session.mongo.connectionString;;
The string defining the MongoURI value, such as `mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]`.
More information on how to format the MongoURI string can be found in the https://docs.mongodb.com/manual/reference/connection-string/[official documentation for mongo.]
+
-____
[NOTE]
+====
You will only use *one* `connection-type` at a time, `address` or `uri`.
If both are utilized in your `session-store-mongo.ini`, only the last `connection-type` configured in the file will be used.
By default, the `connection-type` of `address` is used.
-____
+====
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-sessioncache.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-sessioncache.adoc
index d0bde26df2ec..dba25fa8cab5 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-sessioncache.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-sessioncache.adoc
@@ -26,7 +26,7 @@ If you wish to change any of the default values, you need to enable the `session
Once the `session-cache-hash` module has been enabled, you can view a list of all the configurable values by opening `start.d/session-cache-hash.ini`:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
--module=session-cache-hash
@@ -47,11 +47,10 @@ Values are:
* 0 : sessions are evicted from the cache as soon as the last active request for it finishes
* >= 1 : any positive number is the time in seconds after which a session that is in the cache but has not experienced any activity will be evicted
-____
[NOTE]
+====
If you are not using a `SessionDataStore` that persists sessions, be aware that evicted sessions will be lost.
-____
-
+====
jetty.session.saveOnInactiveEvict::
Boolean, default `false`.
Controls whether a session will be saved to the `SessionDataStore` just prior to its eviction.
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/session-hierarchy.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/session-hierarchy.adoc
index 03463d80f7e2..266ae8da8dc3 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/session-hierarchy.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/session-hierarchy.adoc
@@ -47,7 +47,7 @@ There is only one (1) `SessionDataStore` per `SessionCache`.
Visually the session architecture can be represented like this:
-image::images/SessionsHierarchy.png[]
+image::administration/sessions/images/SessionsHierarchy.png[]
==== Configuring Sessions in the Jetty Distribution
diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/sessions-usecases.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/sessions-usecases.adoc
index 81c45b7c4042..85d358da4604 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/sessions-usecases.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/sessions-usecases.adoc
@@ -68,7 +68,7 @@ That said, if a user wishes to configure sessions this way, it is possible using
Below is an example of how you could configure a the link:#configuring-sessions-file-system[`FileSessionDataStore`], but the same concept would apply to any of the *SessionDataStores discussed in this chapter:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -88,8 +88,8 @@ Below is an example of how you could configure a the link:#configuring-sessions-
The example above functions in either a `jetty-web.xml` file or a link:#using-basic-descriptor-files[context xml descriptor file.]
-____
[NOTE]
+====
If you explicitly configure the `SessionCache` and `SessionDataStore` for a `SessionHandler` in a context xml file or `jetty-web.xml` file, any session modules you already have enabled are ignored.
So, for example, if you had enabled the `session-store-gcloud module` for your sever, you could force a particular webapp to use the `FileSessionDataStore` by explicitly configuring it in either a context xml file or a `jetty-web.xml` file as shown above.
-____
+====
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/custom-modules.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/custom-modules.adoc
index 4293459f80c8..b9b63c98f75c 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/custom-modules.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/custom-modules.adoc
@@ -240,8 +240,8 @@ INFO : server initialized in ${jetty.base}/start.d/server.ini
INFO : Base directory was modified
----
-____
[NOTE]
+====
It is important to keep in mind that when activating a dependency, Jetty does not just go one layer down.
If a dependent module also has dependencies they too will be enabled.
-____
+====
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/screen-empty-base-listconfig.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/screen-empty-base-listconfig.adoc
index 4df04dc82641..4227b352e615 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/screen-empty-base-listconfig.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/screen-empty-base-listconfig.adoc
@@ -16,8 +16,8 @@
// ========================================================================
//
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase]$ java -jar $JETTY_HOME/start.jar --list-config
Java Environment:
@@ -67,4 +67,4 @@ No classpath entries and/or version information available show.
Jetty Active XMLs:
------------------
(no xml files specified)
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/screen-empty-base.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/screen-empty-base.adoc
index f0b78c238905..26bda37fb581 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/screen-empty-base.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/screen-empty-base.adoc
@@ -16,8 +16,8 @@
// ========================================================================
//
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[jetty]$ mkdir mybase
[jetty]$ cd mybase
[mybase]$ ls -la
@@ -30,4 +30,4 @@ WARNING: Nothing to start, exiting ...
Usage: java -jar start.jar [options] [properties] [configs]
java -jar start.jar --help # for more information
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/screen-http-webapp-deploy-listconfig.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/screen-http-webapp-deploy-listconfig.adoc
index c932f2d31b81..54039d3c92bf 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/screen-http-webapp-deploy-listconfig.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/screen-http-webapp-deploy-listconfig.adoc
@@ -16,8 +16,8 @@
// ========================================================================
//
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase]$ java -jar $JETTY_HOME/start.jar --list-config
Java Environment:
@@ -83,4 +83,4 @@ ${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-webapp.xml
${jetty.home}/etc/jetty-deploy.xml
${jetty.home}/etc/jetty-http.xml
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/screen-http-webapp-deploy.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/screen-http-webapp-deploy.adoc
index aaa55d8faf43..9686194bd889 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/screen-http-webapp-deploy.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/screen-http-webapp-deploy.adoc
@@ -16,8 +16,8 @@
// ========================================================================
//
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase]$ java -jar $JETTY_HOME/start.jar --add-to-start=http,webapp,deploy
INFO : webapp initialized in ${jetty.base}/start.ini
INFO : server transitively enabled, ini template available with --add-to-start=server
@@ -27,4 +27,4 @@ INFO : http initialized in ${jetty.base}/start.ini
INFO : deploy initialized in ${jetty.base}/start.ini
MKDIR : ${jetty.base}/webapps
INFO : Base directory was modified
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/screen-list-logging-modules.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/screen-list-logging-modules.adoc
index edca90e5f804..7934cbec2ac6 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/screen-list-logging-modules.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/screen-list-logging-modules.adoc
@@ -16,8 +16,8 @@
// ========================================================================
//
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase]$ java -jar $JETTY_HOME/start.jar --list-modules=logging,-internal
Available Modules:
@@ -91,4 +91,4 @@ Modules for tag 'requestlog':
Depend: server, logback-core, resources
LIB: lib/logback/logback-access-${logback.version}.jar
XML: etc/jetty-logback-access.xml
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/screen-list-modules.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/screen-list-modules.adoc
index 4f74ea73041b..d0fb9fd89347 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/screen-list-modules.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/screen-list-modules.adoc
@@ -16,8 +16,8 @@
// ========================================================================
//
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase]$ java -jar ../start.jar --list-modules
Available Modules:
@@ -728,4 +728,4 @@ Modules for tag 'session':
Tags: session
Depend: server
XML: etc/sessions/id-manager.xml
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc
index 12b2651eeab0..50fa5ba36839 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc
@@ -21,12 +21,12 @@
The most basic way of starting the Jetty standalone server is to execute the `start.jar`, which is a bootstrap for starting Jetty with the configuration you want.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[jetty-distribution-{VERSION}]$ java -jar start.jar
2013-09-23 11:27:06.654:INFO:oejs.Server:main: jetty-{VERSION}
...
-....
+----
Jetty is a highly modularized web server container.
Very little is mandatory and required, and most components are optional; you enable or disable them according to the needs of your environment.
@@ -90,10 +90,10 @@ Lists the resolved configuration that will start Jetty.
* Server XML configuration files
--dry-run::
Print the command line that the start.jar generates, then exit. This may be used to generate command lines when the start.ini includes -X or -D arguments:
-....
+----
$ java -jar start.jar --dry-run > jetty.sh
$ . jetty.sh
-....
+----
--dry-run=::
Print specific parts of the command line. The parts are a comma separated list of:
@@ -104,17 +104,17 @@ Print specific parts of the command line. The parts are a comma separated list o
* "args" - the arguments passed to the main class
It is possible to decompose the start command:
-....
+----
$ OPTS=$(java -jar start.jar --dry-run=opts,path)
$ MAIN=$(java -jar start.jar --dry-run=main)
$ ARGS=$(java -jar start.jar --dry-run=args)
$ java $OPTS -Dextra=opt $MAIN $ARGS extra=arg
-....
+----
Alternatively to create an args file for java:
-....
+----
$ java -jar start.jar --dry-run=opts,path,main,args > /tmp/args
$ java @/tmp/args
-....
+----
--exec::
Forces the start to use a forked instance of java to run Jetty.
Some modules include `--exec` in order to set java command line options.
@@ -163,25 +163,25 @@ Note: Transitive modules are also appended.
If a module contains an .ini template with properties, you can also edit these properties when activating the module.
To do this, simply list the property and its value after the `-add-to-start` command, such as in the following example:
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ java -jar start.jar --add-to-start=http jetty.http.port=8379 jetty.http.host=1.2.3.4
-....
+----
+
Doing this will uncomment the property in the associated .ini file and set it to the value specified.
--update-ini::
Used to update a specified property or properties that exist in an existing .ini file.
Jetty scans the command line, `${jetty.base}` and `${jetty.home}` for .ini files that have the specified property and update it accordingly.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ java -jar ../start.jar --update-ini jetty.http.port=8417
ConfigSource
ConfigSource ${jetty.base}
INFO : http property updated jetty.http.port=8417
INFO : http updated ${jetty.base}/start.d/http.ini
ConfigSource ${jetty.home}
-....
+----
+
--create-startd::
Creates a `${jetty.base}/start.d/` directory.
@@ -197,14 +197,14 @@ Please see link:#start-vs-startd[Start.ini vs. Start.d] for more information.
--write-module-graph=::
Advanced feature: Creates a graphviz http://graphviz.org/content/dot-language[dot file] of the module graph as it exists for the active `${jetty.base}`.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# generate module.dot
$ java -jar start.jar --module=websocket --write-module-graph=modules.dot
# post process to a PNG file
$ dot -Tpng -o modules.png modules.dot
-....
+----
+
See http://graphviz.org/[graphviz.org] for details on http://graphviz.org/content/command-line-invocation[how to post-process this dotty file] into the output best suited for your needs.
@@ -216,11 +216,10 @@ This may download a file from the network if the module provides a URL.
Disable the [files] section validation of content in the `${jetty.base}` directory for a specific module.
Useful for modules that have downloadable content that is being overridden with alternatives in the `${jetty.base}`` directory.
-____
[CAUTION]
+====
This advanced option is for administrators that fully understand the configuration of their `${jetty.base}` and are willing to forego some of the safety checks built into the jetty-start mechanism.
-____
-
+====
--approve-all-licenses::
Approve all license questions.
Useful for enabling modules from a script that does not require user interaction.
@@ -252,25 +251,24 @@ You can configure a port number for Jetty to listen on for a stop command, so yo
This requires the use of a "secret" key, to prevent malicious or accidental termination.
Use the `STOP.PORT` and `STOP.KEY` (or `-DSTOP.PORT=` and `-DSTOP.KEY=`, respectively, which will set these as system parameters) parameters as arguments to the `start.jar`:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar ${JETTY_HOME}/start.jar STOP.PORT=1234 STOP.KEY=secretpassword
-....
+----
Then, to stop Jetty from a different terminal, you need to supply this port and key information.
You can either use a copy of the Jetty distribution, the link:#jetty-maven-plugin[jetty-maven-plugin], the link:#jetty-ant[jetty-ant plugin], or a custom class to accomplish this.
Here's how to use the Jetty distribution, leveraging `start.jar`, to perform a stop:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -jar start.jar STOP.PORT=8181 STOP.KEY=abc123 --stop
-....
+----
-____
[NOTE]
+====
To perform a graceful shutdown of Jetty, the `stats` link:#startup-modules[module] *must* be enabled.
-____
-
+====
===== Advanced Commands
--lib=::
@@ -293,34 +291,34 @@ Default is https://repo1.maven.org/maven2/.
==== Shaded Start.jar
If you have a need for a shaded version of `start.jar` (such as for Gradle), you can achieve this via a Maven dependency.
-[source, xml, subs="{sub-order}"]
-....
+[source, xml]
+----
org.eclipse.jetty
jetty-start
{VERSION}
shaded
-....
+----
==== Start.jar without exec or forking.
Some Jetty modules include the `--exec` option so that java command line options can be set.
Also some `start.jar` options (eg. `--jpms`) include an implicit `--exec`.
To start jetty without forking a new JVM instance from the start JVM, the `--dry-run` option can be used to generate a command line:
-....
+----
$ CMD=$(java -jar start.jar --dry-run)
$ $CMD
-....
+----
It is possible to decompose the start command so that it can be modified:
-....
+----
$ OPTS=$(java -jar start.jar --dry-run=opts,path)
$ MAIN=$(java -jar start.jar --dry-run=main)
$ ARGS=$(java -jar start.jar --dry-run=args)
$ java $OPTS -Dextra=opt $MAIN $ARGS extra=arg
-....
+----
Alternatively to create an args file for java:
-....
+----
$ java -jar start.jar --dry-run=opts,path,main,args > /tmp/args
$ java @/tmp/args
-....
\ No newline at end of file
+----
\ No newline at end of file
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/startup-base-vs-home.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/startup-base-vs-home.adoc
index 469f1bf74c9f..04478176fc95 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/startup-base-vs-home.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/startup-base-vs-home.adoc
@@ -30,12 +30,11 @@ Jetty Home::
* Also known as the `${jetty.home}` property.
* This is the location for the Jetty distribution binaries, default XML IoC configurations, and default module definitions.
-____
[IMPORTANT]
+====
Jetty Home should always be treated as a standard of truth.
All configuration modifications, changes and additions should be made in the appropriate Jetty Base directory.
-____
-
+====
[[base-vs-home-resolution]]
Potential configuration is resolved from these 2 directory locations.
@@ -55,8 +54,8 @@ For more details on how startup with start.jar works, see link:#executing-startj
The Jetty Distribution comes with an example `${jetty.base}` which enables the various demonstration webapps and server configurations.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[jetty-distribution-{VERSION}]$ ls -la
total 496
@@ -86,12 +85,12 @@ drwxrwxr-x 2 user group 4096 Oct 8 06:54 webapps/
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/jetty-distribution-{VERSION}/demo-base/webapps/] at interval 1
2013-10-16 09:08:48.072:WARN::main: async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
...
-....
+----
If you want to see what the Jetty base looks like without executing Jetty, you can simply list the configuration by using the `--list-config` command.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[demo-base]$ java -jar $JETTY_HOME/start.jar --list-config
Java Environment:
@@ -213,7 +212,7 @@ Jetty Active XMLs:
${jetty.home}/etc/jetty-rewrite.xml
${jetty.base}/etc/demo-rewrite-rules.xml
${jetty.base}/etc/test-realm.xml
-....
+----
The `--list-config` command line option displays what the configuration will look like when starting Jetty.
This includes information on the Java environment to the system properties, the classpath and the Active Jetty IoC XML used to build up the Jetty server configuration.
@@ -222,8 +221,8 @@ Of note, is that the output will make it known where the configuration elements
If you look at the `${jetty.base}/start.ini` you will see a layout similar to below.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ cat start.ini
# Enable security via jaas, and configure it
@@ -257,7 +256,7 @@ jetty.dump.stop=false
--module=resources
--module=client
--module=annotations
-....
+----
In this example, `${jetty.base}/start.ini` is the main startup configuration entry point for Jetty.
You will see that we are enabling a few modules for Jetty, specifying some properties, and also referencing some Jetty IoC XML files (namely the `etc/demo-rewrite-rules.xml` and `etc/test-realm.xml` files)
@@ -274,8 +273,8 @@ The Jetty `start.jar` and XML files always assume that both `${jetty.home}` and
You can opt to manually define the `${jetty.home}` and `${jetty.base}` directories, such as this:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION}
@@ -286,14 +285,14 @@ You can opt to manually define the `${jetty.home}` and `${jetty.base}` directori
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...
-....
+----
Alternately, you can declare one directory and let the other one be discovered.
The following example uses default discovery of `${jetty.home}` by using the parent directory of wherever `start.jar` itself is, and a manual declaration of `${jetty.base}`.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION}
@@ -302,15 +301,15 @@ The following example uses default discovery of `${jetty.home}` by using the par
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...
-....
+----
But Jetty recommends that you always start Jetty from the directory that is your `${jetty.base}` and starting Jetty by referencing
the `start.jar` in your `{$jetty.home}` remotely.
The following demonstrates this by allowing default discovery of `${jetty.home}` via locating the `start.jar`, and using the `user.dir` System Property for `${jetty.base}`.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION}
@@ -320,10 +319,10 @@ The following demonstrates this by allowing default discovery of `${jetty.home}`
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...
-....
+----
-____
[IMPORTANT]
+====
Be aware of the `user.dir` system property, as it can only be safely set when the JVM starts and many 3rd party libraries (especially logging) use this system property.
It is strongly recommended that you sit in the directory that is your desired `${jetty.base}` when starting Jetty to have consistent behavior and use of the `user.dir` system property.
-____
+====
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/startup-classpath.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/startup-classpath.adoc
index 6708b2a8884f..eacf1d1a97a3 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/startup-classpath.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/startup-classpath.adoc
@@ -42,11 +42,10 @@ Of special note, there are 2 structural modules defined to ease some of this for
+
Logging libraries often have classpath lookup of their configuration files (eg: `log4j.properties`, `log4j.xml`, `logging.properties`, and `logback.xml`), so this would be the ideal setup for this sort of configuration demand.
-____
[NOTE]
+====
Both the `ext` and `resources` modules declare relative paths that follow link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules].
-____
-
+====
==== Interrogating the Server Classpath
The Jetty `start.jar` has the ability to resolve the classpath from the command line, modules and configuration, and to list the classpath entries it will use to start jetty.
@@ -55,8 +54,8 @@ The `--list-classpath` command line option is used as such.
(Demonstrated with the link:#demo-base[demo-base from the Jetty Distribution])
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[demo-base]$ java -jar $JETTY_HOME/start.jar --list-classpath
Jetty Server Classpath:
@@ -106,6 +105,6 @@ Note: order presented here is how they would appear on the classpath.
39: {VERSION} | ${jetty.home}/lib/websocket/websocket-common-{VERSION}.jar
40: {VERSION} | ${jetty.home}/lib/websocket/websocket-server-{VERSION}.jar
41: {VERSION} | ${jetty.home}/lib/websocket/websocket-servlet-{VERSION}.jar
-....
+----
Of note is that an attempt is made to list the internally declared version of each artifact on the Server Classpath, which can potentially help when diagnosing classpath issues.
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/startup-jpms.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/startup-jpms.adoc
index 549fee6e7359..d7a6e767394a 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/startup-jpms.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/startup-jpms.adoc
@@ -36,8 +36,8 @@ or greater, and explicitly referencing the "enterprise" classes as dependencies,
To start Jetty on the module-path rather than the class-path, it is enough to add the `--jpms` option to the command line, for example:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ mkdir my-jetty-base
$ cd my-jetty-base
$ java -jar $JETTY_HOME/start.jar --add-to-start=http
@@ -46,7 +46,7 @@ INFO : http initialized in ${jetty.base}/start.ini
INFO : threadpool transitively enabled, ini template available with --add-to-start=threadpool
INFO : Base directory was modified
$ java -jar $JETTY_HOME/start.jar --jpms
-....
+----
The example above creates a link:#startup-base-and-home[Jetty base directory] and enables the `http` module using the `--add-to-start` command.
The server then starts Jetty on the module-path using the `--jpms` option.
@@ -59,20 +59,20 @@ You will have two JVMs running: one that runs `start.jar` and one that runs Jett
If you are interested in the details of how the command line to run Jetty on the module-path looks like, you can add the `--dry-run` option:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ java -jar $JETTY_HOME/start.jar --jpms --dry-run
-....
+----
This will give an output looking something like this (broken in sections for clarity):
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
/opt/openjdk-11+28/bin/java
--module-path /opt/jetty/lib/servlet-api-3.1.jar:/opt/jetty/lib/jetty-schemas-3.1.jar:/opt/jetty/lib/jetty-http-9.4.13-SNAPSHOT.jar:...
--patch-module servlet.api=/opt/jetty/lib/jetty-schemas-3.1.jar
--module org.eclipse.jetty.xml/org.eclipse.jetty.xml.XmlConfiguration /opt/jetty/etc/jetty-threadpool.xml /opt/jetty/etc/jetty.xml ...
-....
+----
The `--module-path` option specifies the list of Jetty jars.
This list depends on the Jetty modules that have been enabled via the link:#startup-modules[`--add-to-start`] command.
@@ -94,15 +94,15 @@ Jetty needs to be able to instantiate those classes and therefore needs to be ab
When Jetty runs on the class-path, this is easily achieved by using a link:#custom-modules[custom module]:
-[source, screen, subs="{sub-order}"]
+[source, screen]
.mysql.mod
-....
+----
[description]
MySQL module
[lib]
lib/mysql/mysql-connector-java-*.jar
-....
+----
However, when running on the module-path, things are quite different.
@@ -111,9 +111,9 @@ Because it is not an automatic module, it is not added to the module graph, and
To add the JPMS module `java.sql` to the module graph, you need to modify your custom module in the following way, using our `mysql.mod` as an example:
-[source, screen, subs="{sub-order}"]
+[source, screen]
.mysql.mod
-....
+----
[description]
MySQL module
@@ -122,7 +122,7 @@ lib/mysql/mysql-connector-java-*.jar
[jpms]
add-modules: java.sql
-....
+----
The new `[jpms]` section is only used when Jetty is started on the module-path via the `--jpms` command line option.
@@ -130,9 +130,9 @@ Assuming that `mysql-connector-java-*.jar` is a non JPMS modular jar, or an auto
If `mysql-connector-java-*.jar` were a proper JPMS modular jar with name (for example) `com.mysql.jdbc`, then it would need to be explicitly added to the module graph, in this way:
-[source, screen, subs="{sub-order}"]
+[source, screen]
.mysql.mod
-....
+----
[description]
MySQL module
@@ -141,21 +141,21 @@ lib/mysql/mysql-connector-java-*.jar
[jpms]
add-modules: com.mysql.jdbc
-....
+----
The JPMS module `java.sql` does not need to be explicitly added because it would be a dependency of the `com.mysql.jdbc` module and therefore automatically added to the module graph.
The `[jpms]` section has the following format:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[jpms]
add-modules: (,)*
patch-module: =(:)*
add-opens: /=(,)*
add-exports: /=(,)*
add-reads: =(,)*
-....
+----
[[jpms-module-path-alternative]]
==== Alternative way to start Jetty on the module-path
@@ -164,22 +164,22 @@ The section above uses the `--jpms` command line option to start Jetty on the mo
An alternative way of achieving the same result is to use a Jetty module, `$JETTY_BASE/modules/jpms.mod`,
that specifies that you want to run using JPMS (and possibly add some JPMS specific configuration).
-[source, screen, subs="{sub-order}"]
+[source, screen]
.jpms.mod
-....
+----
[ini]
--jpms
[jpms]
# Additional JPMS configuration.
-....
+----
The `[ini]` section is equivalent to passing the `--jpms` option to the command line.
The `[jpms]` section (see also the link:#jpms-advanced-config[advanced JPMS configuration section])
allows you specify additional JPMS configuration.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ mkdir jetty-base-jpms
$ cd jetty-base-jpms
$ mkdir modules
@@ -189,4 +189,4 @@ $ cp /tmp/jpms.mod modules/
$ java -jar $JETTY_HOME/start.jar --add-to-start=http,jpms
# Jetty will start on the module-path.
$ java -jar $JETTY_HOME/start.jar
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/startup-modules.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/startup-modules.adoc
index 440ae61086f4..36da4432b9bd 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/startup-modules.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/startup-modules.adoc
@@ -25,12 +25,11 @@ Modules allow flexibility for implementations and their plug-and-play nature mak
[[enabling-modules]]
==== Enabling Modules
-____
[TIP]
+====
The default distribution has a co-mingled `${jetty.home}` and `${jetty.base}` where the directories for `${jetty.home}` and `${jetty.base}` point to the same location.
It is highly encouraged that you learn about the differences in link:#startup-base-and-home[Jetty Base vs Jetty Home] and take full advantage of this setup.
-____
-
+====
Enabling a module is a simple process: simply add the `--add-to-start=,,...etc.` syntax on the command line.
Doing this will enable the specified module and any dependent modules.
@@ -70,8 +69,8 @@ As an alternative to a single `start.ini` file you can opt to house modules in a
Modules activated when a `start.d` directory exists will be stored as a single file per module.
Below is an example of a fresh `${jetty.base}` that will create a `start.d` directory and activate several modules.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[jetty.home]$ mkdir mybase
[jetty.home]$ cd mybase/
[mybase]$ java -jar ../start.jar --create-startd
@@ -97,7 +96,7 @@ drwxr-xr-x 3 staff staff 102 Aug 29 15:16 ..
-rw-r--r-- 1 staff staff 2250 Aug 29 15:19 server.ini
-rw-r--r-- 1 staff staff 265 Aug 29 15:19 webapp.ini
-rw-r--r-- 1 staff staff 177 Aug 29 15:19 websocket.ini
-....
+----
In the example, we first create a new `${jetty.base}` and then create the `start.d` directory with the `--create-startd` command.
Next, we use the `--add-to-start` command which activates the modules and creates their respective ini files in the `start.d` directory.
@@ -106,8 +105,8 @@ If you have an existing `start.ini` file but would like to use the `start.d` str
Doing this will create the `start.d` directory and copy your existing `start.ini` file in to it.
Any new modules added to the server will have their own `.ini` file created in the `start.d` directory.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase]$ java -jar ../start.jar --add-to-start=server,client,webapp,websocket
INFO : webapp initialised in ${jetty.base}/start.ini
INFO : server initialised in ${jetty.base}/start.ini
@@ -132,7 +131,7 @@ INFO : Base directory was modified
└── start.d
├── ssl.ini
└── start.ini
-....
+----
[NOTE]
--
@@ -148,22 +147,21 @@ This is done by editing the associated ini file for the module.
If your server setup is using a centralized ini configuration, you will edit the `${jetty.base}/server.ini` file.
If you have elected to manage each module within it's own ini file, you can find these files in the `${jetty.base}/start.d` directory.
-____
[IMPORTANT]
+====
It is important that you *do not* modify the module files in the `$JETTY_HOME/modules` directory.
$JETTY_HOME should always remain a standard of truth.
If you want to make a change to an actual module file (not the values in its `ini-template`), either edit its associated `ini` file in the `$JETTY_BASE/start.d` directory or make a copy of the desired module file and copy it to the `$JETTY_BASE` directory and edit it there.
The start.jar reads local `$JETTY_BASE/modules` files (if they exist) before scanning `$JETTY_HOME`.
-____
-
+====
When a module is activated, a number of properties are set by default.
To view these defaults, open up the associated ini file.
Listed in the ini file is the associated module file and any properties that can be set.
Below is an example of the `requestlog.ini` file:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# ---------------------------------------
# Module: requestlog
--module=requestlog
@@ -194,7 +192,7 @@ Below is an example of the `requestlog.ini` file:
## Whether to log LogLatency
# jetty.requestlog.loglatency=false
-....
+----
The first lines name the module file being called (located in `{$jetty.home/modules}`).
Subsequent lines list properties that can be changed as well as a description for each property.
@@ -215,12 +213,11 @@ This command will also show you which modules are __enabled__.
Modules are sorted by the value in the `[tags]` section of the associated `.mod` file.
If there are multiple entries in the `[tags]` section, it sorts by the first tag in the list.
-____
[NOTE]
+====
By default, the `--list-modules` command line argument shows all modules that do not include `internal` in the `[tags]` section of the associated `.mod` file.
If you would like to see *all* modules, use `--list-all-modules`
-____
-
+====
Here's an example of the `--list-modules` command:
include::screen-list-modules.adoc[]
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/startup-overview.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/startup-overview.adoc
index 40f9d0e24598..37424d2db03a 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/startup-overview.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/startup-overview.adoc
@@ -71,17 +71,17 @@ XML Files::
The simplest way to start Jetty is via the `start.jar` mechanism using the following Java command line:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[user]$ cd jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ java -jar start.jar --module=http jetty.http.port=8080
-....
+----
This command uses the `start.jar` mechanism to bootstrap the classpath, properties, and XML files with the metadata obtained from the `http` module.
Specifically the `http` module is defined in the `${jetty.home}/modules/http.mod` file, and includes the following:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[jetty-distribution-{VERSION}]$ cat modules/http.mod
[depend]
server
@@ -92,15 +92,15 @@ etc/jetty-http.xml
[ini-template]
jetty.http.port=8080
http.timeout=30000
-....
+----
The `http` module declares that `http` depends on the server module, uses the `jetty-http.xml` file, and can be parameterized with `jetty.http.port` and `http.timeout` parameters.
The INI-template section is not actually used by the command above, so the `jetty.http.port` must still be defined on the command line.
Following the server dependency, the `${jetty.home}/modules/server.mod` file includes:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[jetty-distribution-{VERSION}]$ cat modules/server.mod
[lib]
lib/servlet-api-3.1.jar
@@ -116,15 +116,15 @@ etc/jetty.xml
[ini-template]
threads.min=10
threads.max=200
-....
+----
The `server` module declares the libraries the server needs and to use `jetty.xml` file.
The combined metadata of the `http` and `server` modules results in `start.jar` generating the effective Java command line required to start Jetty.
Another way to see this is by asking Jetty what its configuration looks like by appending --list-config to the command line:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[jetty-distribution-{VERSION}]$ java -jar start.jar --module=http jetty.http.port=9099 --list-config
Java Environment:
@@ -174,7 +174,7 @@ Jetty Active XMLs:
------------------
${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-http.xml
-....
+----
This represents the entirety of the configuration that is applied to start Jetty.
@@ -182,8 +182,8 @@ If you don't want to use the `start.jar` bootstrap, you can start Jetty using a
The following is the equivalent Java command line for what the `start.jar` bootstrap above performs.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[user]$ cd jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ echo jetty.http.port=8080 > /tmp/jetty.properties
[jetty-distribution-{VERSION}]$ export JETTY_HOME=`pwd`
@@ -203,14 +203,14 @@ org.eclipse.jetty.xml.XmlConfiguration \
/tmp/jetty.properties \
$JETTY_HOME/etc/jetty.xml \
$JETTY_HOME/etc/jetty-http.xml
-....
+----
The Java command line sets up the classpath with the core Jetty jars and the servlet API, executes the XmlConfiguration class and passes it some XML files that define the server and an HTTP connector running on the port defined in the `jetty.properties` file.
You can further simplify the startup of this server by using the INI template defined by the modules to create a `start.ini` file with the command:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[user]$ cd jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ mkdir example-base
[example-base]$ cd example-base
@@ -231,11 +231,11 @@ total 12
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:55 ./
drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
-rw-rw-r-- 1 user webgroup 250 Oct 4 11:55 start.ini
-....
+----
Once complete, you can edit the `start.ini` file to modify any parameters and you can run the server with the simple command:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[example-base]$ java -jar $JETTY_HOME/start.jar
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/startup-unix-service.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/startup-unix-service.adoc
index 5632c4372753..6b4ebd990fed 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/startup-unix-service.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/startup-unix-service.adoc
@@ -27,8 +27,8 @@ This script is suitable for setting up Jetty as a service in Unix.
The minimum steps to get Jetty to run as a Service include:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[/opt/jetty]# tar -zxf /home/user/downloads/jetty-distribution-{VERSION}.tar.gz
[/opt/jetty]# cd jetty-distribution-{VERSION}/
[/opt/jetty/jetty-distribution-{VERSION}]# ls
@@ -43,7 +43,7 @@ JETTY_HOME=/opt/jetty/jetty-distribution-{VERSION}
[/opt/jetty/jetty-distribution-{VERSION}]# service jetty start
Starting Jetty: OK Wed Nov 20 10:26:53 MST 2013
-....
+----
From this demonstration we can see that Jetty started successfully as a Unix Service from the `/opt/jetty/jetty-distribution-{VERSION}` directory.
@@ -57,12 +57,12 @@ The techniques outlined here assume an installation on Linux (demonstrated on Ub
Prepare some empty directories to work with.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# mkdir -p /opt/jetty
# mkdir -p /opt/web/mybase
# mkdir -p /opt/jetty/temp
-....
+----
The directory purposes are as follows:
@@ -79,15 +79,15 @@ It is our experience that the standard temp directory is often managed by variou
Jetty 9.3 requires Java 8 (or greater) to run.
Make sure you have it installed.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# apt-get install openjdk-8-jdk
-....
+----
Or download Java 8 from: http://www.oracle.com/technetwork/java/javase/downloads/index.html
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# java -version
java version "1.6.0_27"
OpenJDK Runtime Environment (IcedTea6 1.12.6) (6b27-1.12.6-1ubuntu0.12.04.2)
@@ -113,15 +113,15 @@ update-alternatives: using /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java to pro
java version "1.7.0_25"
OpenJDK Runtime Environment (IcedTea 2.3.10) (7u25-2.3.10-1ubuntu0.12.04.2)
OpenJDK 64-Bit Server VM (build 23.7-b01, mixed mode)
-....
+----
It is recommended that you create a user to specifically run Jetty.
This user should have the minimum set of privileges needed to run Jetty.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# useradd --user-group --shell /bin/false --home-dir /opt/jetty/temp jetty
-....
+----
This will create a user called `jetty`, belonging to the group called `jetty`, with no shell access (aka `/bin/false`), and home directory at `/opt/jetty/temp`.
@@ -129,13 +129,13 @@ Download a copy of the Jetty distribution from the link:#jetty-downloading[Offic
Unpack it into place.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[/opt/jetty]# tar -zxf /home/user/Downloads/jetty-distribution-{VERSION}.tar.gz
[/opt/jetty]# ls -F
jetty-distribution-{VERSION}/
[/opt/jetty]# mkdir /opt/jetty/temp
-....
+----
It might seem strange or undesirable to unpack the first portion of the jetty-distribution directory name too.
But starting with Jetty 9 the split between `${jetty.home}` and `${jetty.base}` allows for easier upgrades of Jetty itself while isolating your webapp specific configuration.
@@ -153,8 +153,8 @@ In past versions of Jetty, you would configure / modify / add to the `jetty-dist
While this is still supported, we encourage you to setup a proper `${jetty.base}` directory, as it will benefit you with easier `jetty-distribution` upgrades in the future.
--
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# cd /opt/web/mybase/
[/opt/web/mybase]# ls
[/opt/web/mybase]# java -jar /opt/jetty/jetty-distribution-{VERSION}/start.jar \
@@ -171,7 +171,7 @@ While this is still supported, we encourage you to setup a proper `${jetty.base}
INFO : Base directory was modified
[/opt/web/mybase]# ls -F
start.ini webapps/
-....
+----
At this point you have configured your `/opt/web/mybase` to enable the following modules:
@@ -191,44 +191,44 @@ See xref:start-jar[] for more details and options on setting up and configuring
Copy your war file into place.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# cp /home/user/projects/mywebsite.war /opt/web/mybase/webapps/
-....
+----
Most service installations will want Jetty to run on port 80, now is the opportunity to change this from the default value of `8080` to `80`.
Edit the `/opt/web/mybase/start.ini` and change the `jetty.http.port` value.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# grep jetty.http.port /opt/web/mybase/start.ini
jetty.port=80
-....
+----
Change the permissions on the Jetty distribution and webapp directories so that the user you created can access it.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# chown --recursive jetty /opt/jetty
# chown --recursive jetty /opt/web/mybase
-....
+----
Next we need to make the Unix System aware that we have a new Jetty Service that can be managed by the standard `service` calls.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# cp /opt/jetty/jetty-distribution-{VERSION}/bin/jetty.sh /etc/init.d/jetty
# echo "JETTY_HOME=/opt/jetty/jetty-distribution-{VERSION}" > /etc/default/jetty
# echo "JETTY_BASE=/opt/web/mybase" >> /etc/default/jetty
# echo "JETTY_USER=jetty" >> /etc/default/jetty
# echo "TMPDIR=/opt/jetty/temp" >> /etc/default/jetty
-....
+----
Test out the configuration:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# service jetty status
Checking arguments to Jetty:
START_INI = /opt/web/mybase/start.ini
@@ -254,14 +254,14 @@ RUN_CMD = /usr/bin/java
-jar /opt/jetty/jetty-distribution-{VERSION}/start.jar
console-capture.xml
jetty-started.xml
-....
+----
You now have a configured `${jetty.base}` in `/opt/web/mybase` and a `${jetty.home}` in `/opt/jetty/jetty-distribution-{VERSION}`, along with the service level files necessary to start the service.
Test the service to make sure it starts up and runs successfully.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# service jetty start
Starting Jetty: OK Wed Nov 20 12:35:28 MST 2013
@@ -272,6 +272,6 @@ Jetty running pid=2958
[/opt/web/mybase]# ps u 2958
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
jetty 2958 5.3 0.1 11179176 53984 ? Sl 12:46 0:00 /usr/bin/java -Djetty...
-....
+----
You should now have your server running.
diff --git a/jetty-documentation/src/main/asciidoc/administration/startup/startup-windows-service.adoc b/jetty-documentation/src/main/asciidoc/administration/startup/startup-windows-service.adoc
index b6e0fa9bdb88..b549f7bc1990 100644
--- a/jetty-documentation/src/main/asciidoc/administration/startup/startup-windows-service.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/startup/startup-windows-service.adoc
@@ -27,8 +27,8 @@ The techniques outlined here are based on Windows 7 (64-bit), using JDK 8 (64-bi
Prepare some empty directories to work with.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
C:\> mkdir opt
C:\> cd opt
C:\opt> mkdir jetty
@@ -48,7 +48,7 @@ C:\opt> dir
11/21/2013 04:06 PM myappbase
11/21/2013 04:06 PM temp
0 File(s) 0 bytes
-....
+----
The directory purposes are as follows:
@@ -69,13 +69,13 @@ This is intentionally kept separate from the standard temp directories of Window
Or download Java 8 from: http://www.oracle.com/technetwork/java/javase/downloads/index.html
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
C:\opt>java -version
java version "1.7.0_45"
Java(TM) SE Runtime Environment (build 1.7.0_45-b18)
Java HotSpot(TM) 64-Bit Server VM (build 24.45-b08, mixed mode)
-....
+----
Download a copy of the ZIP distribution from the link:#jetty-downloading[Official Eclipse Download Site]
@@ -83,8 +83,8 @@ Extract the contents of the `jetty-distribution-{VERSION}` directory to `C:\opt\
Once complete, the contents of the `C:\opt\jetty` directory should look like this:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
C:\opt\jetty>dir
Volume in drive C has no label.
Volume Serial Number is C8CF-820B
@@ -110,7 +110,7 @@ C:\opt\jetty>dir
11/21/2013 12:13 PM webapps
6 File(s) 453,659 bytes
11 Dir(s) 306,711,420,928 bytes free
-....
+----
Download a copy of the https://commons.apache.org/proper/commons-daemon/binaries.html[Apache ProcRun] native binaries.
@@ -122,8 +122,8 @@ The ZIP file has both 32 bit and 64 bit versions of this file.
Once you are complete, the contents of `C:\opt` directory should look like this:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
C:\opt> dir
Volume in drive C has no label.
Volume Serial Number is DEAD-BEEF
@@ -139,14 +139,14 @@ C:\opt> dir
11/21/2013 04:11 PM 104,448 prunmgr.exe
11/21/2013 04:11 PM 80,896 prunsrv.exe
2 File(s) 185,344 bytes
-....
+----
Now it's time to setup your new `${jetty.base}` directory to have all of your WebApps and the configurations that they need.
We'll start by specifying which modules we want to use (this will create a start.ini file and also create a few empty directories for you)
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
C:\opt\myappbase>java -jar ..\jetty\start.jar --add-to-start=deploy,http,console-capture
WARNING: deploy initialised in ${jetty.base}\start.ini (appended)
@@ -174,7 +174,7 @@ C:\opt\myappbase>dir
11/21/2013 12:49 PM webapps
1 File(s) 1,355 bytes
4 Dir(s) 306,711,064,576 bytes free
-....
+----
At this point you have configured your `C:\opt\myappbase` to enable the following modules:
@@ -192,10 +192,10 @@ See the section on xref:start-jar[] for more details and options on setting up a
At this point you merely have to copy your WAR files into the `{$jetty.base}/webapps` directory.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
C:\opt\myappbase> copy C:\projects\mywebsite.war webapps\
-....
+----
At this point you should have your directories, Java, the Jetty distribution, and your webapp specifics setup and ready for operation.
@@ -295,4 +295,4 @@ Once you have run `prunsrv.exe //IS/` (done for you in the above b
Open the Service View and start your service.
-image:images/windows-service-jetty.png[image,width=576]
+image:administration/strartup/images/windows-service-jetty.png[image,width=576]
diff --git a/jetty-documentation/src/main/asciidoc/administration/tuning/garbage-collection.adoc b/jetty-documentation/src/main/asciidoc/administration/tuning/garbage-collection.adoc
index 72772966b434..8afb0d074210 100644
--- a/jetty-documentation/src/main/asciidoc/administration/tuning/garbage-collection.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/tuning/garbage-collection.adoc
@@ -31,8 +31,8 @@ These options are general to OpenJDK (and therefore also for the Oracle JVM).
They provide good information about the GC activity of your JVM, producing logs that can later be analyzed to perform finer tuning.
.JDK 8 Garbage Collection Logging Configuration
-[source,screen, subs="{sub-order}"]
-....
+[source,screen]
+----
-Xloggc:/path/to/myjettybase/logs/gc.log
-XX:+PrintGCDateStamps
-XX:+PrintGCDetails
@@ -40,18 +40,18 @@ They provide good information about the GC activity of your JVM, producing logs
-XX:+PrintReferenceGC
-XX:+PrintTenuringDistribution
-XX:+PrintAdaptiveSizePolicy
-....
+----
.JDK 9 Garbage Collection Logging Configuration
-[source,screen, subs="{sub-order}"]
-....
+[source,screen]
+----
Xlog:gc*,ergo*=trace,ref*=debug,age*=trace:file=/path/to/myjettybase/logs/gc.log:time,level,tags
-....
+----
There are not many recommended options for GC that can apply to all users.
However, the most obvious one is to disable explicit GC (this is performed regularly by RMI and can introduce an abnormal amount of GC pauses).
-[source,screen, subs="{sub-order}"]
-....
+[source,screen]
+----
-XX:+DisableExplicitGC
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/administration/tuning/high-load.adoc b/jetty-documentation/src/main/asciidoc/administration/tuning/high-load.adoc
index 4e929369c26c..6a5f3bad0250 100644
--- a/jetty-documentation/src/main/asciidoc/administration/tuning/high-load.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/tuning/high-load.adoc
@@ -54,13 +54,13 @@ You can configure most of these in `/etc/security/limits.conf` or via `sysctl`.
You should increase TCP buffer sizes to at least 16MB for 10G paths and tune the auto-tuning (keep in mind that you need to consider buffer bloat).
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ sysctl -w net.core.rmem_max=16777216
$ sysctl -w net.core.wmem_max=16777216
$ sysctl -w net.ipv4.tcp_rmem="4096 87380 16777216"
$ sysctl -w net.ipv4.tcp_wmem="4096 16384 16777216"
-....
+----
====== Queue Sizes
@@ -69,59 +69,59 @@ The default value is 128.
If you are running a high-volume server and connections are getting refused at a TCP level, you need to increase this value.
This setting can take a bit of finesse to get correct: if you set it too high, resource problems occur as it tries to notify a server of a large number of connections, and many remain pending, but if you set it too low, refused connections occur.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ sysctl -w net.core.somaxconn=4096
-....
+----
The `net.core.netdev_max_backlog` controls the size of the incoming packet queue for upper-layer (Java) processing.
The default (2048) may be increased and other related parameters adjusted with:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ sysctl -w net.core.netdev_max_backlog=16384
$ sysctl -w net.ipv4.tcp_max_syn_backlog=8192
$ sysctl -w net.ipv4.tcp_syncookies=1
-....
+----
====== Ports
If many outgoing connections are made (for example, on load generators), the operating system might run low on ports.
Thus it is best to increase the port range, and allow reuse of sockets in `TIME_WAIT`:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ sysctl -w net.ipv4.ip_local_port_range="1024 65535"
$ sysctl -w net.ipv4.tcp_tw_recycle=1
-....
+----
====== File Descriptors
Busy servers and load generators may run out of file descriptors as the system defaults are normally low.
These can be increased for a specific user in `/etc/security/limits.conf`:
-....
+----
theusername hard nofile 40000
theusername soft nofile 40000
-....
+----
====== Congestion Control
Linux supports pluggable congestion control algorithms.
To get a list of congestion control algorithms that are available in your kernel run:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ sysctl net.ipv4.tcp_available_congestion_control
-....
+----
If cubic and/or htcp are not listed, you need to research the control algorithms for your kernel.
You can try setting the control to cubic with:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ sysctl -w net.ipv4.tcp_congestion_control=cubic
-....
+----
====== Mac OS
diff --git a/jetty-documentation/src/main/asciidoc/administration/tuning/limit-load.adoc b/jetty-documentation/src/main/asciidoc/administration/tuning/limit-load.adoc
index f940663a136f..ca4f00040563 100644
--- a/jetty-documentation/src/main/asciidoc/administration/tuning/limit-load.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/tuning/limit-load.adoc
@@ -26,7 +26,7 @@ To achieve optimal fair handling for all users of a server, it can be necessary
An instance of link:{JDURL}/org/eclipse/jetty/server/LowResourceMonitor.html[LowResourceMonitor] may be added to a Jetty server to monitor for low resources situations and to take action to limit the number of idle connections on the server.
To configure the low resources monitor, you can enable the the `lowresources.mod` on the command line, which has the effect of including the following XML configuration:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/jetty-server/src/main/config/etc/jetty-lowresources.xml[]
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-connectors.adoc b/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-connectors.adoc
index a88102ee9d2b..ef1b14356dd3 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-connectors.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-connectors.adoc
@@ -34,8 +34,8 @@ Additional settings, including construction your own constructor Jetty XML files
Out of the box, Jetty provides several link:#startup-modules[modules] for enabling different types of connectors, from HTTP to HTTPS, HTTP/2, and others.
If you startup Jetty with the `--list-modules=connector` command, you can see a list of all available connector modules:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase]$ java -jar $JETTY_HOME/start.jar --list-modules=connector
Available Modules:
@@ -178,13 +178,13 @@ Modules for tag 'connector':
Depend: unixsocket-http
XML: etc/jetty-unixsocket-secure.xml
...
-....
+----
To enable a connector, simply activate the associated module.
Below is an example of activating both the `http` and `https` modules in a fresh link:#startup-base-and-home[Jetty base] using the link:#start-vs-startd[start.d directory]:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase] java -jar $JETTY_HOME/start.jar --create-startd
MKDIR : ${jetty.base}/start.d
INFO : Base directory was modified
@@ -204,14 +204,14 @@ INFO : Base directory was modified
└── start.d
├── http.ini
└── https.ini
-....
+----
When the `http` and `https` modules were activated, so too were any modules they were dependent on, in this case `server` and `ssl`, as well as any dependencies for those modules, such as the `etc` and `ketystore` directories for `ssl`.
At this point the server has been configured with connectors for both HTTP and HTTPS and can be started:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase] java -jar $JETTY_HOME/start.jar
2017-08-31 10:19:58.855:INFO::main: Logging initialized @372ms to org.eclipse.jetty.util.log.StdErrLog
2017-08-31 10:19:59.076:INFO:oejs.Server:main: jetty-9.4.6.v20170531
@@ -220,14 +220,14 @@ At this point the server has been configured with connectors for both HTTP and H
2017-08-31 10:19:59.151:INFO:oejus.SslContextFactory:main: x509=X509@5d624da6(mykey,h=[],w=[]) for SslContextFactory@2ef9b8bc(file:///Users/staff/installs/repository/jetty-distribution-{VERSION}/mybase/etc/keystore,file:///Users/staff/installs/repository/jetty-distribution-{VERSION}/mybase/etc/keystore)
2017-08-31 10:19:59.273:INFO:oejs.AbstractConnector:main: Started ServerConnector@2b98378d{SSL,[ssl, http/1.1]}{0.0.0.0:8443}
2017-08-31 10:19:59.274:INFO:oejs.Server:main: Started @791ms
-....
+----
When modules are enabled, they are loaded with several default options.
These can be changed by editing the associated module ini file in the `start.d` directory (or the associated lines in `server.ini` if your implementation does not use `start.d`).
For example, if we examine the `http.ini` file in our `start.d` directory created above, we will see the following settings:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# ---------------------------------------
# Module: http
# Enables a HTTP connector on the server.
@@ -261,41 +261,40 @@ For example, if we examine the `http.ini` file in our `start.d` directory create
## HTTP Compliance: RFC7230, RFC2616, LEGACY
# jetty.http.compliance=RFC7230
-....
+----
To make a change to these settings, uncomment the line (by removing the #) and change the property to the desired value.
For example, if you wanted to change the HTTP port to 5231, you would edit the line as follows:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
...
## Connector port to listen on
jetty.http.port=5231
...
-....
+----
Now when the server is started, HTTP connections will enter on port 5231:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[mybase] java -jar ../start.jar
2017-08-31 10:31:32.955:INFO::main: Logging initialized @366ms to org.eclipse.jetty.util.log.StdErrLog
2017-08-31 10:31:33.109:INFO:oejs.Server:main: jetty-9.4.6.v20170531
2017-08-31 10:31:33.146:INFO:oejs.AbstractConnector:main: Started ServerConnector@2ef9b8bc{HTTP/1.1,[http/1.1]}{0.0.0.0:5231}
...
2017-08-31 10:31:33.263:INFO:oejs.Server:main: Started @675ms
-....
+----
Every module has their own set of configuration options, and reviewing them all is recommended.
For additional information on the module system, please refer to our documentation on link:#startup-modules[Startup Modules].
-____
[NOTE]
+====
Editing these module files is the recommended way to edit the configuration of your server.
Making changes to the associated Jetty XML file for connectors is *not* recommended, and is for advanced users only.
If you do wish to edit Jetty XML, please see our section on managing link:#[Jetty Home and Jetty Base] to ensure your Jetty Home remains a standard of truth for your implementation.
-____
-
+====
==== Limiting Connections
Jetty also provides the means by which to limit connections to the server and/or contexts.
@@ -338,7 +337,7 @@ link:{GITBROWSEURL}/jetty-alpn/jetty-alpn-server/src/main/config/etc/jetty-alpn.
The services a link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] instance uses are set by constructor injection and once instantiated cannot be changed.
Many of the services may be defaulted with null or 0 values so that a reasonable default is used, thus for most purposes only the Server and the connection factories need to be passed to the connector constructor. In Jetty XML (that is, in link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-http.xml[`jetty-http.xml`]) you can do this by:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
]
@@ -360,7 +359,7 @@ Typically the defaults are sufficient for almost all deployments.
You can configure connector network settings by calling setters on the connector before it is started.
For example, you can set the port with the Jetty XML:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -373,7 +372,7 @@ For example, you can set the port with the Jetty XML:
Values in Jetty XML can also be parameterized so that they may be passed from property files or set on the command line.
Thus typically the port is set within Jetty XML, but uses the `Property` element to be customizable:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -418,7 +417,7 @@ To avoid duplicate configuration, the standard Jetty distribution creates the co
A typical configuration of link:{JDURL}/org/eclipse/jetty/server/HttpConfiguration.html[HttpConfiguration] is:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
https
@@ -431,7 +430,7 @@ A typical configuration of link:{JDURL}/org/eclipse/jetty/server/HttpConfigurati
This example HttpConfiguration may be used by reference to the ID "`httpConfig`":
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -457,7 +456,7 @@ Please note that if your `httpConfig` does not include a `secureScheme` or `secu
For SSL-based connectors (in `jetty-https.xml` and `jetty-http2.xml`), the common "`httpConfig`" instance is used as the basis to create an SSL specific configuration with ID "`sslHttpConfig`":
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -484,19 +483,18 @@ In such environments, the TCP/IP connection terminating on the server does not o
Thus Intermediaries typically implement one of several de facto standards to communicate to the server information about the original client connection terminating on the intermediary.
Jetty supports the `X-Forwarded-For` header and the http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt[Proxy Protocol] mechanisms as described below.
-____
[NOTE]
+====
The XML files in the Jetty distribution contain commented out examples of both the `X-Forwarded-For` and http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt[Proxy Protocol] mechanisms.
When using those examples, it is recommended that the XML in the Jetty distribution is not edited.
Rather the files should be copied into a Jetty base directory and then modified.
-____
-
+====
===== X-Forward-for Configuration
The `X-Forwarded-for` header and associated headers are a de facto standard where intermediaries add HTTP headers to each request they forward to describe the originating connection.
These headers can be interpreted by an instance of link:{JDURL}/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[`ForwardedRequestCustomizer`] which can be added to a `HttpConfiguration` as follows:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
32768
@@ -519,7 +517,7 @@ The connection factory can be added to any link:{JDURL}/org/eclipse/jetty/server
An example of adding the factory to a HTTP connector is shown below:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl-distribution.adoc b/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl-distribution.adoc
index 656cddd602f7..2c1b3a360db7 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl-distribution.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl-distribution.adoc
@@ -27,7 +27,7 @@ provider and the https://github.com/google/conscrypt/[Conscrypt] provider as SSL
For the default SSL support, simply activate the `ssl` link:#startup-modules[module]:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
$ cd /path/to/mybase
$ java -jar ${JETTY_HOME}/start.jar --add-to-startd=ssl
@@ -63,7 +63,7 @@ jetty.sslContext.keyStorePassword::
Enabling Conscrypt SSL is just as easy as default SSL - enable both the `conscrypt` and `ssl` link:#startup-modules[modules]:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
$ cd ${JETTY_HOME}
$ java -jar ../start.jar --add-to-start=ssl,conscrypt
@@ -98,7 +98,7 @@ SSL-specific parameters, like `keyStorePath` and `keyStorePassword` can still co
To enable client certificate authentication in the Jetty Distribution, you need to enable the both the `ssl` and `https` modules.
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
$ cd /path/to/mybase
$ java -jar /path/to/jetty-dist/start.jar --add-to-startd=ssl,https
diff --git a/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl.adoc b/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl.adoc
index 6e9e65e9b1d4..93f49d151d34 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl.adoc
@@ -43,17 +43,16 @@ All CBC based ciphers are supported since Java 7, the new GCM modes are supporte
TLS v1.0, v1.1 and SSL v3 are no longer supported by default. If your Jetty implementation requires these protocols for legacy support, they can be enabled manually.
-____
[NOTE]
+====
Once TLS v1.3 is released, there will be no workaround available for TLS v1.0 or v1.1.
Plans for TLS v1.3 include banning ciphers with known vulnerabilities from being present at any level.
It is recommended to upgrade any clients using these ciphers as soon as possible or face being locked into a outdated version of Jetty, Java or even OS.
-____
-
+====
By default, Jetty excludes these ciphers in the link:{GITBROWSEURL}/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SslContextFactory.java#L249-L256[`SslContextFactory`.]
You can re-enable these by re-declaring the ciphers you want excluded in code:
-[source, java, subs="{sub-order}"]
+[source, java]
----
SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
sslContextFactory.setExcludeCipherSuites("^.*_(MD5|SHA|SHA1)$");
@@ -110,23 +109,22 @@ You should read the full manuals of the tools you are using if you want to speci
The following command generates a key pair and certificate directly into file `keystore`:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA
----
-____
[NOTE]
+====
The DSA key algorithm certificate produces an error after loading several pages.
In a browser, it displays a message "Could not establish an encrypted connection because certificate presented by localhost as an invalid signature."
The solution is to use RSA for the key algorithm.
-____
-
+====
This command prompts for information about the certificate and for passwords to protect both the keystore and the keys within it.
The only mandatory response is to provide the fully qualified host name of the server at the "first and last name" prompt.
For example:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA
Enter keystore password: password
@@ -159,7 +157,7 @@ If you want to use only a self signed certificate for some kind of internal admi
If you are using Java 8 or later, then you may also use the SAN extension to set one or more names that the certificate applies to:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA -ext 'SAN=dns:jetty.eclipse.org,dns:*.jetty.org'
...
@@ -170,7 +168,7 @@ $ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256with
The following command generates a key pair in the file `jetty.key`:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ openssl genrsa -aes128 -out jetty.key
----
@@ -179,7 +177,7 @@ You might also want to use the `-rand` file argument to provide an arbitrary fil
The following command generates a certificate for the key into the file `jetty.crt`:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ openssl req -new -x509 -newkey rsa:2048 -sha256 -key jetty.key -out jetty.crt
----
@@ -190,7 +188,7 @@ For the those with heightened security in mind, add -b4096 to get a 4069 bit key
The next command prompts for information about the certificate and for passwords to protect both the keystore and the keys within it.
The only mandatory response is to provide the fully qualified host name of the server at the "Common Name" prompt. For example:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ openssl genrsa -aes128 -out jetty.key
Generating RSA private key, 2048 bit long modulus
@@ -243,7 +241,7 @@ Each CA has its own instructions (look for JSSE or OpenSSL sections), but all in
The following command generates the file `jetty.csr` using `keytool` for a key/cert already in the keystore:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ keytool -certreq -alias jetty -keystore keystore -file jetty.csr
----
@@ -253,7 +251,7 @@ $ keytool -certreq -alias jetty -keystore keystore -file jetty.csr
The following command generates the file `jetty.csr` using OpenSSL for a key in the file `jetty.key`:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ openssl req -new -key jetty.key -out jetty.csr
----
@@ -266,13 +264,12 @@ You need to enter the details for the certificate again.
Once a CA has sent you a certificate, or if you generated your own certificate without `keytool`, you need to load it into a JSSE keystore.
-____
[NOTE]
+====
You need both the private key and the certificate in the JSSE keystore.
You should load the certificate into the keystore used to generate the CSR with `keytool`.
If your key pair is not already in a keystore (for example, because it has been generated with OpenSSL), you need to use the PKCS12 format to load both key and certificate (see link:#loading-keys-and-certificates-via-pkcks12[PKCKS12 Keys &Certificates]).
-____
-
+====
[[loading-certificates-with-keytool]]
====== Loading Certificates with keytool
@@ -280,7 +277,7 @@ You can use `keytool` to load a certificate in PEM form directly into a keystore
The PEM format is a text encoding of certificates; it is produced by OpenSSL, and is returned by some CAs.
An example PEM file is:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
jetty.crt
-----BEGIN CERTIFICATE-----
@@ -302,14 +299,14 @@ Rcz6oCRvCGCe5kDB
The following command loads a PEM encoded certificate in the `jetty.crt` file into a JSSE keystore:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ keytool -keystore keystore -import -alias jetty -file jetty.crt -trustcacerts
----
If the certificate you receive from the CA is not in a format that `keytool` understands, you can use the `openssl` command to convert formats:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ openssl x509 -in jetty.der -inform DER -outform PEM -out jetty.crt
----
@@ -322,29 +319,28 @@ The certificate can be one you generated yourself or one returned from a CA in r
The following OpenSSL command combines the keys in `jetty.key` and the certificate in the `jetty.crt` file into the `jetty.pkcs12` file:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ openssl pkcs12 -inkey jetty.key -in jetty.crt -export -out jetty.pkcs12
----
If you have a chain of certificates, because your CA is an intermediary, build the PKCS12 file as follows:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ cat example.crt intermediate.crt [intermediate2.crt] ... rootCA.crt > cert-chain.txt
$ openssl pkcs12 -export -inkey example.key -in cert-chain.txt -out example.pkcs12
----
-____
[NOTE]
+====
The order of certificates must be from server to rootCA, as per link:https://www.ietf.org/rfc/rfc2246.txt[RFC2246 section 7.4.2.]
-____
-
+====
OpenSSL asks for an __export password__.
A non-empty password is required to make the next step work.
Load the resulting PKCS12 file into a JSSE keystore with `keytool`:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ keytool -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destkeystore keystore
----
@@ -361,11 +357,11 @@ If you imported the key and certificate originally using the PKCS12 method, use
The `keystore` only contains the server's private key and certificate.
[[img-certificate-chain]]
-image::images/certificate-chain.png[title="Certificate chain", alt="Certificate chain"]
+image::configuring/connectors/images/certificate-chain.png[title="Certificate chain", alt="Certificate chain"]
[literal]
.The structure of KeyStore file:
-....
+----
├── PrivateKeyEntry
│ ├── PrivateKey
│ ├── Certificate chain
@@ -376,13 +372,12 @@ image::images/certificate-chain.png[title="Certificate chain", alt="Certificate
│ └── Intermediary CA certificate
└── TrustedCertEntry
└── Root CA certificate
-....
+----
-____
[NOTE]
+====
Both the `Intermediary CA certificate` and `Root CA certificate` are optional.
-____
-
+====
[source%nowrap,plain,linenums]
----
$ cd $JETTY_BASE
@@ -644,21 +639,21 @@ the other is `$JETTY/etc/truststore` which contains intermediary CA and root CA.
[literal]
.The structure of `$JETTY/etc/keystore`
-....
+----
└── PrivateKeyEntry
├── PrivateKey
└── Certificate chain
└── Server certificate (end entity)
-....
+----
[literal]
.The structure of `$JETTY/etc/truststore`
-....
+----
├── TrustedCertEntry
│ └── Intermediary CA certificate
└── TrustedCertEntry
└── Root CA certificate
-....
+----
[[configuring-sslcontextfactory]]
==== Configuring the Jetty SslContextFactory
@@ -686,11 +681,10 @@ While the `SslContextFactory` can operate without a keystore (this mode is most
setKeyStorePath::
The configured keystore to use for all SSL/TLS in configured Jetty Connector (or Client).
-____
[NOTE]
+====
As a keystore is vital security information, it can be desirable to locate the file in a directory with *very* restricted access.
-____
-
+====
setKeyStorePassword::
The keystore password may be set here in plain text, or as some measure of protection from casual observation, it may be obfuscated using the link:{JDURL}/org/eclipse/jetty/util/security/Password.html[Password] class.
setTrustStorePath::
@@ -704,26 +698,24 @@ setExcludeCipherSuites / setIncludeCipherSuites::
setExcludeProtocols / setIncludeProtocols::
This allows for the customization of the selected Protocols that will be used by SSL/TLS.
-____
[NOTE]
+====
When working with Includes / Excludes, it is important to know that *Excludes will always win.*
The selection process is to process the JVM list of available Cipher Suites or Protocols against the include list, then remove the excluded ones.
Be aware that each Include / Exclude list has a Set method (replace the list) or Add method (append the list).
-____
-
-____
+====
[CAUTION]
+====
The keystore and truststore passwords may also be set using the system properties: `org.eclipse.jetty.ssl.keypassword` `org.eclipse.jetty.ssl.password`.
This is _not_ a recommended usage.
-____
-
+====
[[conscrypt]]
==== Conscrypt SSL
Jetty includes support for Google's https://github.com/google/conscrypt/[Conscrypt SSL], which is built on their fork of https://www.openssl.org/[OpenSSL], https://boringssl.googlesource.com/boringssl/[BoringSSL].
Implementing Conscrypt for the link:{GITBROWSEURL}/jetty-alpn/jetty-alpn-conscrypt-server/src/test/java/org/eclipse/jetty/alpn/conscrypt/server/ConscryptHTTP2Server.java[server] or link:{GITBROWSEURL}/jetty-alpn/jetty-alpn-conscrypt-client/src/test/java/org/eclipse/jetty/alpn/java/client/ConscryptHTTP2Client.java[client] is very straightforward process - simply instantiate an instance of Conscrypt's `OpenSSLProvider` and set `Conscrypt` as a provider for Jetty's `SslContextFactory`:
-[source, java, subs="{sub-order}"]
+[source, java]
----
...
Security.addProvider(new OpenSSLProvider());
@@ -760,31 +752,28 @@ It's crucial that you use the _exact_ names of the cipher suites as used/known b
You can get them by obtaining an instance of SSLEngine and call `getSupportedCipherSuites()`.
Tools like https://www.ssllabs.com/[ssllabs.com] might report slightly different names which will be ignored.
-____
[IMPORTANT]
+====
It is important to stay up-to-date with the latest supported cipher suites.
Be sure to consult Oracle's link:https://java.com/en/jre-jdk-cryptoroadmap.html[JRE and JDK Cryptographic Roadmap] frequently for recent and upcoming changes to supported ciphers.
-____
-
-____
+====
[IMPORTANT]
+====
It's recommended to install the Java Cryptography Extension (JCE) Unlimited Strength policy files in your JRE to get full strength ciphers such as AES-256.
The files can be found on the http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java download page].
Just overwrite the two present JAR files in `/lib/security/`.
-____
-
+====
Both `setIncludeCipherSuites` and `setExcludeCipherSuites` can be fed by the exact cipher suite name used in the JDK or by using regular expressions.
If you have a need to adjust the Includes or Excludes, then this is best done with a custom XML that configures the `SslContextFactory` to suit your needs.
-____
[NOTE]
+====
Jetty *does* allow users to enable weak/deprecated cipher suites (or even no cipher suites at all).
By default, if you have these suites enabled warning messages will appear in the server logs.
-____
-
+====
To do this, first create a new `${jetty.base}/etc/tweak-ssl.xml` file (this can be any name, just avoid prefixing it with "jetty-").
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -808,7 +797,7 @@ You can do anything you want with the `SslContextFactory` in use by the Jetty Di
To make sure that your `${jetty.base}` uses this new XML, add it to the end of your `${jetty.base}/start.ini` or `${jetty.base}/start.d/server.ini`.
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
$ cd /path/to/mybase
$ ls -l
@@ -821,23 +810,21 @@ etc/tweak-ssl.xml
$
----
-____
[NOTE]
+====
The default `SslContextFactory` implementation applies the latest SSL/TLS recommendations surrounding vulnerabilities in SSL/TLS.
Check the release notes (the `VERSION.txt` found in the root of the Jetty Distribution, or the http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.eclipse.jetty%22%20AND%20a%3A%22jetty-project%22[alternate (classified 'version') artifacts for the `jetty-project` component] on Maven Central) for updates.
The Java JVM also applies exclusions at the JVM level and, as such, if you have a need to enable something that is generally accepted by the industry as being insecure or vulnerable you will likely have to enable it in *both* the Java JVM and your Jetty configuration.
-____
-
-____
+====
[TIP]
+====
You can enable the `org.eclipse.jetty.util.ssl` named logger at `DEBUG` level to see what the list of selected Protocols and Cipher suites are at startup of Jetty.
-____
-
+====
Additional Include / Exclude examples:
*Example*: Include all ciphers which support https://en.wikipedia.org/wiki/Forward_secrecy[Forward Secrecy] using regex:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -851,7 +838,7 @@ Additional Include / Exclude examples:
*Example*: Exclude all old, insecure or anonymous cipher suites:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -869,7 +856,7 @@ Additional Include / Exclude examples:
*Example*: Since 2014 SSLv3 is considered insecure and should be disabled.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -884,14 +871,13 @@ Additional Include / Exclude examples:
----
-____
[NOTE]
+====
Note that disabling SSLv3 prevents very old browsers like Internet Explorer 6 on Windows XP from connecting.
-____
-
+====
*Example*: TLS renegotiation could be disabled too to prevent an attack based on this feature.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
FALSE
----
@@ -905,7 +891,7 @@ You can also dump the server when shutting down the server instance by adding `j
Specifically, you will want to look for the `SslConnectionFactory` portion of the dump.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
[my-base]$ java -jar ${JETTY_HOME}/start.jar jetty.server.dumpAfterStart=true
diff --git a/jetty-documentation/src/main/asciidoc/configuring/contexts/configuring-virtual-hosts.adoc b/jetty-documentation/src/main/asciidoc/configuring/contexts/configuring-virtual-hosts.adoc
index 3fc4bd0c1762..78db7794dc45 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/contexts/configuring-virtual-hosts.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/contexts/configuring-virtual-hosts.adoc
@@ -62,7 +62,7 @@ You supply a list of IP addresses and names at which the web application is reac
Suppose you have a webapp called `blah.war`, that you want all of the above names and addresses to be served at path "`/blah`".
Here's how you would configure the virtual hosts with a link:#deployable-descriptor-file[context XML] file:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -102,7 +102,7 @@ Using the method of preparing link:#deployable-descriptor-file[contextXML] files
For `blah` webapp:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -128,7 +128,7 @@ These URLs now resolve to the blah context (ie `blah.war`):
For `other` webapp:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -177,7 +177,7 @@ To achieve this, we simply use the same context path of `/` for each of our weba
For foo webapp:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -197,7 +197,7 @@ For foo webapp:
For bar webapp:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/contexts/custom-error-pages.adoc b/jetty-documentation/src/main/asciidoc/configuring/contexts/custom-error-pages.adoc
index 137e8e427148..d15e94fe5c05 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/contexts/custom-error-pages.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/contexts/custom-error-pages.adoc
@@ -32,7 +32,7 @@ This element creates a mapping between the error-code or exception-type to the l
Error code example:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
404
@@ -43,7 +43,7 @@ Error code example:
Exception example:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
java.io.IOException
@@ -74,7 +74,7 @@ javax.servlet.error.status_code::
You can use context IoC XML files to configure the default error page mappings with more flexibility than is available with `web.xml`, specifically with the support of error code ranges.
Context files are normally located in `${jetty.base}/webapps/` (see `DeployerManager` for more details) and an example of more flexible error page mapping is below:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -122,7 +122,7 @@ Context files are normally located in `${jetty.base}/webapps/` (see `DeployerMan
If no error page mapping is defined, or if the error page resource itself has an error, then the error page will be generated by an instance of `ErrorHandler` configured either the Context or the Server.
An `ErrorHandler` may extend the `ErrorHandler` class and may totally replace the handle method to generate an error page, or it can implement some or all of the following methods to partially modify the error pages:
-[source, java, subs="{sub-order}"]
+[source, java]
----
void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) throws IOException
void handleErrorPage(HttpServletRequest request, Writer writer, int code, String message) throws IOException
@@ -136,7 +136,7 @@ void writeErrorPageStacks(HttpServletRequest request, Writer writer) throws IOEx
An `ErrorHandler` instance may be set on a Context by calling the `ContextHandler.setErrorHandler` method. This can be done by embedded code or via context IoC XML.
For example:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
...
@@ -150,7 +150,7 @@ For example:
An `ErrorHandler` instance may be set on the entire server by setting it as a dependent bean on the Server instance.
This can be done by calling `Server.addBean(Object)` via embedded code or in `jetty.xml` IoC XML:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
...
diff --git a/jetty-documentation/src/main/asciidoc/configuring/contexts/serving-webapp-from-particular-port.adoc b/jetty-documentation/src/main/asciidoc/configuring/contexts/serving-webapp-from-particular-port.adoc
index 0b60c79cb116..400ed0ced4b5 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/contexts/serving-webapp-from-particular-port.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/contexts/serving-webapp-from-particular-port.adoc
@@ -35,14 +35,14 @@ When creating new configurations for alternative server:
* Change all `id="Server"` to the new server name:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
----
* For all connectors for the new server change the `refid` in the server argument:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
----
@@ -55,14 +55,14 @@ When creating new configurations for alternative server:
The following example creates another server instance and configures it with a connector and deployer:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/examples/embedded/src/main/resources/jetty-otherserver.xml[]
----
To run the other server, add the extra configuration file(s) to the command line:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
java -jar start.jar jetty-otherserver.xml
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/contexts/setting-context-path.adoc b/jetty-documentation/src/main/asciidoc/configuring/contexts/setting-context-path.adoc
index 0b646a497387..a328ab0738cd 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/contexts/setting-context-path.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/contexts/setting-context-path.adoc
@@ -45,7 +45,7 @@ If a web application is deployed using the WebAppProvider of the DeploymentManag
If a web application is deployed using the `WebAppProvider` of the `DeploymentManager` with an XML IoC file to configure the context, then the `setContextPath` method can be called within that file.
For example:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
/test
diff --git a/jetty-documentation/src/main/asciidoc/configuring/contexts/setting-form-size.adoc b/jetty-documentation/src/main/asciidoc/configuring/contexts/setting-form-size.adoc
index 8f0fc5a8333e..1a484ffede92 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/contexts/setting-form-size.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/contexts/setting-form-size.adoc
@@ -32,7 +32,7 @@ This can be done either in a context XML deployment descriptor external to the w
In either case the syntax of the XML file is the same:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -46,7 +46,7 @@ In either case the syntax of the XML file is the same:
Set an attribute in `jetty.xml` on the Server instance for which you want to modify the maximum form content size:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -56,20 +56,19 @@ Set an attribute in `jetty.xml` on the Server instance for which you want to mod
----
-____
[IMPORTANT]
+====
It is important to remember that you should *not* modify the XML files in your `$JETTY_HOME`.
If you do for some reason feel you want to change the way an XML file operates, it is best to make a copy of it in your `$JETTY_BASE` in an `/etc` directory.
Jetty will always look first to the `$JETTY_BASE` for configuration.
-____
-
+====
==== For All Apps in the JVM
Use the system property `org.eclipse.jetty.server.Request.maxFormContentSize`.
This can be set on the command line or in the `$JETTY_BASE\start.ini` or any `$JETTY_BASE\start.d\*.ini` link:#startup-modules[module ini file.]
Using `$JETTY_BASE\start.d\server.ini` as an example:
-[source, console, subs="{sub-order}"]
+[source, console]
----
# ---------------------------------------
# Module: server
diff --git a/jetty-documentation/src/main/asciidoc/configuring/contexts/temporary-directories.adoc b/jetty-documentation/src/main/asciidoc/configuring/contexts/temporary-directories.adoc
index d8503c14d94a..2c83a7e86b83 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/contexts/temporary-directories.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/contexts/temporary-directories.adoc
@@ -27,15 +27,15 @@ Whether you set the location of the temporary directory - or you let Jetty creat
By default, Jetty will create a temporary directory for each web application. The name of the directory will be of the form:
-....
+----
"jetty-"+host+"-"+port+"-"+resourceBase+"-_"+context+"-"+virtualhost+"-"+randomdigits+".dir"
-....
+----
For example:
-....
+----
jetty-0.0.0.0-8080-test.war-_test-any-8900275691885214790.dir
-....
+----
Where `0.0.0.0` is the host address, `8080` is the port, `test.war` is the resourceBase, `test` is the context path (with / converted to _), `any` is the virtual host, and `randomdigits` are a string of digits guaranteed to be unique.
@@ -51,7 +51,7 @@ As usual with Jetty, you can either set this attribute in a context xml file, or
Here's an example of setting it in an xml file:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -67,7 +67,7 @@ Here's an example of setting it in an xml file:
The equivalent in code is:
-[source, java, subs="{sub-order}"]
+[source, java]
----
WebAppContext context = new WebAppContext();
context.setContextPath("/test");
@@ -83,7 +83,7 @@ There are several ways to use a particular directory as the temporary directory:
As before this can be accomplished with an XML file or directly in code.
Here is an example of setting the temp directory in XML:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -96,7 +96,7 @@ Here is an example of setting the temp directory in XML:
And here is an example of doing it with java code:
-[source, java, subs="{sub-order}"]
+[source, java]
----
WebAppContext context = new WebAppContext();
context.setContextPath("/test");
@@ -108,7 +108,7 @@ context.setTempDirectory(new File("/some/dir/foo"));
You should set this context attribute with the name of directory you want to use as the temp directory.
Again, you can do this in XML:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -125,7 +125,7 @@ Again, you can do this in XML:
Or in java:
-[source, java, subs="{sub-order}"]
+[source, java]
----
WebAppContext context = new WebAppContext();
context.setContextPath("/test");
@@ -135,17 +135,16 @@ context.setAttribute("javax.servlet.context.tempdir", "/some/dir/foo");
Once a temporary directory has been created by either of these methods, a file instance for it is set as the value of the `javax.servlet.context.tempdir` attribute of the web application.
-____
[NOTE]
+====
Be wary of setting an explicit temp directory if you are likely to change the jars in WEB-INF/lib between redeployments.
There is a JVM bug concerning link:http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4774421[caching of jar contents.]
-____
-
+====
===== Setting the Temp Directory on the Command Line
You can set the location of the temp directory on the command line when Jetty starts up in two ways.
First is the most straightforward, simply add it to your command line when starting Jetty.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
java -jar ../start.jar -Djava.io.tmpdir=/path/to/desired/directory
----
@@ -156,8 +155,8 @@ After enabling the module (using the `--add-to-start=jvm` command), edit the `jv
You will also need verify the line including the `--exec` command is not commented out, as this is required for Jetty to start a new, forked JVM.
Below is an example of the standard `jvm.ini` file altered to include a reference to a temp directory.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
# ---------------------------------------
# Module: jvm
# A noop module that creates an ini template useful for
@@ -187,7 +186,7 @@ Below is an example of the standard `jvm.ini` file altered to include a referenc
# -XX:+PrintCommandLineFlags
# -XX:+DisableExplicitGC
-Djava.io.tmpdir=/path/to/desired/directory
-....
+----
==== The "work" Directory
@@ -204,7 +203,7 @@ Sometimes it is useful to keep the contents of the temporary directory between r
By default, Jetty will *not* persist the temp directory.
To configure Jetty to keep it, use link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext.setPersistTempDirectory(true)].
-____
[NOTE]
+====
Be aware that if you call `setPersistTempDirectory(true)`, but let Jetty create a new temp directory each time (i.e. you do NOT set an explicit temp directory), then you will accumulate temp directories in your chosen temp directory location.
-____
+====
diff --git a/jetty-documentation/src/main/asciidoc/configuring/deploying/configuring-specific-webapp-deployment.adoc b/jetty-documentation/src/main/asciidoc/configuring/deploying/configuring-specific-webapp-deployment.adoc
index 33f7e2460cd0..979660f7027c 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/deploying/configuring-specific-webapp-deployment.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/deploying/configuring-specific-webapp-deployment.adoc
@@ -43,7 +43,7 @@ contextPath::
For example, here is a descriptor file that deploys the file `/opt/myapp/myapp.war` to the context path `/wiki`:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -57,7 +57,7 @@ For example, here is a descriptor file that deploys the file `/opt/myapp/myapp.w
Both `SystemProperty` and `Property` elements can be used in the descriptor file.
For example, if the system property is set to `myapp.home=/opt/myapp`, the previous example can be rewritten as:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -71,11 +71,10 @@ For example, if the system property is set to `myapp.home=/opt/myapp`, the previ
If the home path for an application needs altered, only the system property needs changed.
This is useful if the version of an app is frequently changed.
-____
[NOTE]
+====
To ensure your `web.xml` files are validated, you will need to set the `validateXml` attribute to true as described link:#jetty-xml-dtd[here.]
-____
-
+====
[[configuring-advanced-descriptor-files]]
==== Configuring Advanced Descriptor Files
@@ -85,7 +84,7 @@ Here are some examples that configure advanced options in the descriptor file.
This first example tells Jetty not to expand the WAR file when deploying it.
This can help make it clear that users should not make changes to the temporary unpacked WAR because such changes do not persist, and therefore do not apply the next time the web application deploys.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -101,7 +100,7 @@ The next example retrieves the JavaEE Servlet context and sets an initialization
The `setAttribute` method can also be used to set a Servlet context attribute.
However, since the `web.xml` for the web application is processed after the deployment descriptor, the `web.xml` values overwrite identically named attributes from the deployment descriptor.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -122,7 +121,7 @@ The following example sets a special `web.xml` override descriptor.
This descriptor is processed after the web application's `web.xml`, so it may override identically named attributes.
This feature is useful when adding parameters or additional Servlet mappings without breaking open a packed WAR file.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -137,7 +136,7 @@ This feature is useful when adding parameters or additional Servlet mappings wit
The next example configures not only the web application context, but also a database connection pool (see xref:jndi-datasource-examples[]) that the application can then use.
If the `web.xml` does not include a reference to this data source, an override descriptor mechanism (as shown in the previous example) can be used to include it.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-architecture.adoc b/jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-architecture.adoc
index ac493dfa61bb..aafe0a3f16b2 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-architecture.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-architecture.adoc
@@ -27,7 +27,7 @@ The Jetty distribution contains example `DeploymentManager` configurations to de
The `DeploymentManager` is the heart of the typical webapp deployment mechanism; it operates as a combination of an Application LifeCycle Graph, Application Providers that find and provide Applications into the Application LifeCycle Graph, and a set of bindings in the graph that control the deployment process.
-image:images/Jetty_DeployManager_DeploymentManager_Roles.png[image,width=195]
+image:configuring/deploying/images/Jetty_DeployManager_DeploymentManager_Roles.png[image,width=195]
[[udm-application-providers]]
==== Application Providers
@@ -40,7 +40,7 @@ The main `AppProvider` with the Jetty distribution is the link:{JDURL}/org/eclip
The core feature of the `DeploymentManager` is the link:{JDURL}/org/eclipse/jetty/deploy/AppLifeCycle.html[Application LifeCycle Graph].
-image:images/Jetty_DeployManager_AppLifeCycle-1.png[image,width=340]
+image:configuring/deploying/images/Jetty_DeployManager_AppLifeCycle-1.png[image,width=340]
The nodes and edges of this graph are pre-defined in Jetty along the most common actions and states found.
These nodes and edges are not hardcoded; they can be adjusted and added to depending on need (for example, any complex requirements for added workflow, approvals, staging, distribution, coordinated deploys for a cluster or cloud, etc.).
@@ -68,7 +68,7 @@ There are four default bindings:
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardStopper.html[`StandardStopper`] — Stops the ContextHandler and stops accepting incoming requests.
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardUndeployer.html[`StandardUndeployer`] — Removes the ContextHandler from Jetty.
-image:images/Jetty_DeployManager_DefaultAppLifeCycleBindings.png[image,width=851]
+image:configuring/deploying/images/Jetty_DeployManager_DefaultAppLifeCycleBindings.png[image,width=851]
A fifth, non-standard binding, called link:{JDURL}/org/eclipse/jetty/deploy/bindings/DebugBinding.html[DebugBinding], is also available for debugging reasons; it logs the various transitions through the Application LifeCycle.
@@ -81,7 +81,7 @@ The format for the XML file is the same as any context XML file and can be used
To use this binding, you can either modify the existing `jetty-deploy.xml` which comes with the Jetty distribution (be sure to link:#startup-base-and-home[copy it to your $JETTY_BASE/etc directory first]), or by link:#custom-modules[creating a new module] file which calls to an additional XML file.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -101,7 +101,7 @@ It supports hot (re)deployment.
The basic operation of the `WebAppProvider` is to periodically scan a directory for deployables.
In the standard Jetty Distribution, this is configured in the `${jetty.home}/etc/jetty-deploy.xml` file.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-processing-webapps.adoc b/jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-processing-webapps.adoc
index a65fb8470a15..fe55c72f2de2 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-processing-webapps.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-processing-webapps.adoc
@@ -132,7 +132,7 @@ If you have only one webapp that you wish to affect, this may be the easiest opt
You will, however, either need to have a context xml file that represents your web app, or you need to call the equivalent in code.
Let's see an example of how we would add in the Configurations for both JNDI _and_ annotations:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -164,7 +164,7 @@ Of course, you can also use this method to reduce the Configurations applied to
If you use the link:#deployment-architecture[deployer], you can set up the list of Configuration classes on the link:#default-web-app-provider[WebAppProvider].
They will then be applied to each `WebAppContext` deployed by the deployer:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -208,7 +208,7 @@ Instead of having to enumerate the list in its entirety, you can simply nominate
Let's look at an example of using this method to add in Configuration support for JNDI - as usual you can either do this in an xml file, or via equivalent code.
This example uses an xml file, in fact it is the `$JETTY_HOME/etc/jetty-plus.xml` file from the Jetty distribution:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -258,7 +258,7 @@ The value of this attribute is a regexp that defines which _jars_ and _class dir
Here's an example from a context xml file (although as always, you could have accomplished the same in code), which would match any jar whose name starts with "foo-" or "bar-", or a directory named "classes":
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -284,7 +284,7 @@ This can be particularly useful when you have dozens of jars in `WEB-INF/lib`, b
Here's an example in a xml file of a pattern that matches any jar that starts with `spring-`:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/deploying/hot-deployment.adoc b/jetty-documentation/src/main/asciidoc/configuring/deploying/hot-deployment.adoc
index 1f2ef43f2aba..97483cb00797 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/deploying/hot-deployment.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/deploying/hot-deployment.adoc
@@ -36,7 +36,7 @@ The default location for this configuration is in the `${jetty.home}/etc/jetty-d
To modify it as part of the Jetty distribution, first enable the `deploy` module.
Once it is enabled, you can edit these properties in either the `$JETTY_BASE/start.d/deploy.ini` or `$JETTY_BASE/start.ini` file, depending on link:#start-vs-startd[how your implementation is configured.]
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# ---------------------------------------
diff --git a/jetty-documentation/src/main/asciidoc/configuring/deploying/quickstart-webapp.adoc b/jetty-documentation/src/main/asciidoc/configuring/deploying/quickstart-webapp.adoc
index b8def9d08dff..154bda85545b 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/deploying/quickstart-webapp.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/deploying/quickstart-webapp.adoc
@@ -42,7 +42,7 @@ Tests have shown that webapps that took many seconds to scan and deploy can now
In a standard Jetty distribution the quickstart module can be configured with the following command:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ java -jar $JETTY_HOME/start.jar --add-to-start=quickstart
----
@@ -51,7 +51,7 @@ $ java -jar $JETTY_HOME/start.jar --add-to-start=quickstart
In a Maven project you add a dependency on the artifact `jetty-quickstart`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -81,16 +81,15 @@ generateOrigin::
If true, the origin attribute will be inserted into each element in quickstart-web.xml.
Note that origin attributes will also be generated if debug log level is enabled.
-____
[NOTE]
+====
If you are using Spring-Boot you must set `generateOrigin` to true.
-____
-
+====
The origin is either a descriptor eg web.xml,web-fragment.xml,override-web.xml file, or an annotation eg @WebServlet.
For xml validation each attribute must be unique, and therefore an integer counter is appended to each value.
Some examples of elements with origin attribute information are:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -102,7 +101,7 @@ Some examples of elements with origin attribute information are:
If a web application already has a context xml file, eg `webapps/myapp.xml` file, simply change the class in the `Configure` element.
Otherwise, create a context xml file with the following information (in addition to the usual setting of contextPath, war etc):
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -131,7 +130,7 @@ Note that you will need to provide all necessary jetty jars on the command line
This will unpack the war if necessary, and create the `quickstart-web.xml` before the first deployment:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ java -cp [jetty classpath] org.eclipse.jetty.quickstart.PreconfigureQuickStartWar myapp.war
----
@@ -158,7 +157,7 @@ Of course precompiling JSPs is an excellent way to improve the start time of a w
As of Jetty 9.2 the Apache Jasper JSP implementation has been used and has been augmented to allow the TLD scan to be skipped.
This can be done by adding a `context-param` to the `web.xml` file (this is done automatically by the Jetty Maven JSPC plugin):
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty.jsp.precompiled
@@ -172,7 +171,7 @@ The Jetty `start.jar` mechanism is a very powerful and flexible mechanism for co
However, this mechanism does take some time to build the `classpath`.
The start.jar mechanism can be bypassed by using the `–dry-run` option to generate and reuse a complete command line to start Jetty at a later time:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ RUN=$(java -jar $JETTY_HOME/start.jar --dry-run)
$ eval $RUN
diff --git a/jetty-documentation/src/main/asciidoc/configuring/deploying/static-content-deployment.adoc b/jetty-documentation/src/main/asciidoc/configuring/deploying/static-content-deployment.adoc
index 0394a02f6517..8c9397138f79 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/deploying/static-content-deployment.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/deploying/static-content-deployment.adoc
@@ -22,7 +22,7 @@
To serve purely static content, the Jetty Deployment Descriptor XML concepts and the internal `ResourceHandler` can be used.
Create a file called `scratch.xml` in the `${jetty.base}/webapps` directory and paste the following file contents in it.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/jsp/configuring-jsp.adoc b/jetty-documentation/src/main/asciidoc/configuring/jsp/configuring-jsp.adoc
index b54dedf2a396..f88515d0b7f2 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/jsp/configuring-jsp.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/jsp/configuring-jsp.adoc
@@ -28,7 +28,7 @@ Jetty uses Jasper from http://tomcat.apache.org/tomcat-8.0-doc/jasper-howto.html
By default the Jetty distribution enables the JSP link:#startup-modules[module], and by default, this module is set to Apache Jasper.
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
include::{SRCDIR}/jetty-home/src/main/resources/modules/jsp.mod[]
----
@@ -55,7 +55,7 @@ You can do this using a servlet context init-param called `org.eclipse.jetty.ser
For example, suppose you have precompiled your JSPs with the custom package prefix of `com.acme`, then you would add the following lines to your `web.xml` file:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty.servlet.jspPackagePrefix
@@ -63,11 +63,10 @@ For example, suppose you have precompiled your JSPs with the custom package pref
----
-____
[NOTE]
+====
Both Jetty Maven plugins - link:#jetty-jspc-maven-plugin[jetty-jspc-maven-plugin] and the link:#jetty-maven-plugin[jetty-maven-plugin] - will only use Apache Jasper.
-____
-
+====
[[compiling-jsps]]
===== Apache JSP Container
@@ -161,11 +160,10 @@ Parameters also differ among the various versions of the JSP engine.
This page lists the configuration parameters, their meanings, and their default settings.
Set all parameters on the `org.apache.jasper.servlet.JspServlet` instance defined in the link:#webdefault-xml[`webdefault.xml`] file.
-____
[NOTE]
+====
Be careful: for all of these parameters, if the value you set doesn't take effect, try using all lower case instead of camel case, or capitalizing only some of the words in the name, as JSP is inconsistent in its parameter naming strategy.
-____
-
+====
[[modifying-configuration]]
==== Modifying Configuration
@@ -175,7 +173,7 @@ ____
You can make a copy of the link:#webdefault-xml[{$jetty.home}/etc/webdefault.xml] that ships with Jetty, apply your changes, and use it instead of the shipped version.
The example below shows how to do this when using the Jetty Maven plugin.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -189,7 +187,7 @@ The example below shows how to do this when using the Jetty Maven plugin.
If you are using the Jetty distribution, and you want to change the JSP settings for just one or a few of your webapps, copy the `{$jetty.home}/etc/webdefault.xml` file somewhere, modify it, and then use a link:#intro-jetty-configuration-contexts[context xml] file to set this file as the `defaultsDescriptor` for your webapp. Here's a snippet:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
/foo
@@ -207,7 +205,7 @@ Another option is to add an entry for the JSPServlet to the `WEB-INF/web.xml` fi
You may also add (but not remove) servlet-mappings.
You can use the entry in link:#webdefault-xml[{$jetty.home}/etc/webdefault.xml] as a starting point.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
jsp
@@ -253,7 +251,7 @@ You can use the entry in link:#webdefault-xml[{$jetty.home}/etc/webdefault.xml]
By default, Jetty does not enable async support for the JSP servlet.
Configuring the JSP servlet for async is relatively easy - simply define the `async-supported` parameter as `true` in either your `webdefault.xml` or the `web.xml` for a specific context.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
jsp
@@ -284,7 +282,7 @@ To take advantage of this efficiency enhancement, set up the link:#container-inc
The link:#embedded-examples[Embedded Examples] section includes a link:#embedded-webapp-jsp[worked code example] of how to do this.
Below is a snippet from the example:
-[source, java, subs="{sub-order}"]
+[source, java]
----
webapp.setAttribute("org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern",".*/[^/]*taglibs.*\\.jar$");
----
@@ -306,7 +304,7 @@ You can either put them into the lib directory for Apache `{$jetty.home}/lib/apa
You should make your JSF jars dependencies of the plugin and _not_ the webapp itself.
For example:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
diff --git a/jetty-documentation/src/main/asciidoc/configuring/part.adoc b/jetty-documentation/src/main/asciidoc/configuring/part.adoc
index c2d10f550d8c..3a8b7e12c4e4 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/part.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/part.adoc
@@ -18,7 +18,7 @@
[[jetty-config-guide]]
-= Jetty Configuration Guide
+== Jetty Configuration Guide
include::deploying/chapter.adoc[]
include::contexts/chapter.adoc[]
diff --git a/jetty-documentation/src/main/asciidoc/configuring/security/authentication.adoc b/jetty-documentation/src/main/asciidoc/configuring/security/authentication.adoc
index 9ba49f9bee05..8d202792290a 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/security/authentication.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/security/authentication.adoc
@@ -35,7 +35,7 @@ Internally, configuring an authentication mechanism is done by setting an instan
Below is an example taken from the link:{GITBROWSEURL}/tests/test-webapps/test-jetty-webapp/src/main/webapp/WEB-INF/web.xml?h=release-9[jetty-test-webapp web.xml] that configures BASIC authentication:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
BASIC
@@ -46,7 +46,7 @@ Below is an example taken from the link:{GITBROWSEURL}/tests/test-webapps/test-j
The link:{GITBROWSEURL}/tests/test-webapps/test-jetty-webapp/src/main/webapp/WEB-INF/web.xml?h=release-9[jetty-test-webapp web.xml] also includes commented out examples of other DIGEST and FORM configuration:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
FORM
@@ -62,7 +62,7 @@ The link:{GITBROWSEURL}/tests/test-webapps/test-jetty-webapp/src/main/webapp/WEB
With FORM Authentication, you must also configure URLs of pages to generate a login form and handle errors.
Below is a simple HTML form from the link:{GITBROWSEURL}/tests/test-webapps/test-jetty-webapp/src/main/webapp/logon.html?h=release-9[test webapp logon.html]:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
FORM Authentication demo
@@ -129,7 +129,7 @@ A LoginService is available to all web applications on a Server instance if you
Such a definition would go into an xml file in your `${jetty.base}/etc` directory, e.g. `${jetty.base}/etc/my-realm.xml` and you would add this xml file to the execution path via `start.ini` or `start.d` (you may want to review the material in the link:#startup[Starting Jetty] chapter).
Here's an example of an xml file that defines an in-memory type of LoginService called the link:{JDURL}/org/eclipse/jetty/security/HashLoginService.html[HashLoginService]:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -151,7 +151,7 @@ If you define more than one `LoginService` on a Server, you will need to specify
You can do that by telling the context the name of the `LoginService`, or passing it the `LoginService` instance.
Here's an example of doing both of these, using a link:#deployable-descriptor-file[context xml file]:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -176,7 +176,7 @@ Here's an example of doing both of these, using a link:#deployable-descriptor-fi
Alternatively, you can define a `LoginService` for just a single web application.
Here's how to define the same HashLoginService, but inside a link:#deployable-descriptor-file[context xml file]:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -254,7 +254,7 @@ guest: guest,read-only
You configure the `HashLoginService` with a name and a reference to the location of the properties file:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
-
@@ -268,7 +268,7 @@ You configure the `HashLoginService` with a name and a reference to the location
You can also configure it to reload the configuration file when changes to it are detected.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -362,7 +362,7 @@ If you want to use obfuscated, MD5 hashed or encrypted passwords the `pwd` colum
You define a `JDBCLoginService` with the name of the realm and the location of the properties file describing the database:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
Test JDBC Realm
@@ -380,7 +380,7 @@ Until Servlet 3.1, role-based authorization could define:
* Access granted to a set of named roles:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -396,7 +396,7 @@ Until Servlet 3.1, role-based authorization could define:
* Access totally forbidden, regardless of role:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -410,7 +410,7 @@ Until Servlet 3.1, role-based authorization could define:
* Access granted to a user in any of the roles defined in the effective `web.xml`.
This is indicated by the special value of `*` for the `` of a `` in the ``:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -428,7 +428,7 @@ Servlet 3.1 introduced an additional authorization:
* Access granted to any user who is authenticated, regardless of roles.
This is indicated by the special value of `**` for the `` of a `` in the ``:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -445,7 +445,7 @@ Additionally, when configuring your security constraints you can protect various
This is done by adding the method you want to protect as a `` in the ``.
You can then define roles that should be able to perform these protected methods in an ``:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -470,7 +470,7 @@ This is especially helpful if authorization needs change over time and need upda
To do this, we add a section for security constraints into the context xml file for our web app as part of the `securityHandler`.
In the example below, a `HashLoginService` is defined with authorization being granted too `foo/*` paths to users with the `admin` and `manager` roles.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -512,7 +512,7 @@ If roles changed in the future, administrators could easily change this context
In addition to the distribution, security can be defined as part of an embedded implementation as well.
Below is an example which, like the one above, sets up a server with a `HashLoginService` and adds security constraints to restrict access based on roles.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/SecuredHelloHandler.java[]
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/security/configuring-form-size.adoc b/jetty-documentation/src/main/asciidoc/configuring/security/configuring-form-size.adoc
index 57a21870d8fe..b857f2e56b96 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/security/configuring-form-size.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/security/configuring-form-size.adoc
@@ -35,7 +35,7 @@ There exists 2 system properties that will adjust the default maximum form sizes
Used from command line as such:
-[source,shell,subs="{sub-order}"]
+[source,shell]
----
$ java -Dorg.eclipse.jetty.server.Request.maxFormKeys=200 -jar ...
@@ -45,7 +45,7 @@ $ java -Dorg.eclipse.jetty.server.Request.maxFormContentSize=400000 -jar ...
Or via Java code (make sure you do this before you instantiate any `ContextHandler`, `ServletContextHandler`, or `WebAppContext`)
-[source,java,subs="{sub-order}"]
+[source,java]
----
System.setProperty(ContextHandler.MAX_FORM_KEYS_KEY, "200");
System.setProperty(ContextHandler.MAX_FORM_CONTENT_SIZE_KEY, "400000");
@@ -56,7 +56,7 @@ System.setProperty(ContextHandler.MAX_FORM_CONTENT_SIZE_KEY, "400000");
To configure the form limits for a single web application, the context handler (or webappContext) instance must be configured using the following methods:
-[source,java,subs="{sub-order}"]
+[source,java]
----
ContextHandler.setMaxFormContentSize(int maxSizeInBytes);
ContextHandler.setMaxFormKeys(int formKeys);
@@ -65,7 +65,7 @@ ContextHandler.setMaxFormKeys(int formKeys);
These methods may be called directly when embedding Jetty, but more commonly are configured from a context XML file or WEB-INF/jetty-web.xml file:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/security/jaas-support.adoc b/jetty-documentation/src/main/asciidoc/configuring/security/jaas-support.adoc
index 9e4c311dc92b..83b60fb960bf 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/security/jaas-support.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/security/jaas-support.adoc
@@ -54,7 +54,7 @@ Let's look at an example.
Configure a Jetty `org.eclipse.jetty.jaas.JAASLoginService` to match the `` in your `web.xml` file. For example, if the `web.xml` contains a realm called "Test JAAS Realm" like so:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
FORM
@@ -68,7 +68,7 @@ Configure a Jetty `org.eclipse.jetty.jaas.JAASLoginService` to match the `
Test JAAS Realm
@@ -77,17 +77,16 @@ then you need to create a `JAASLoginService` with the matching realm name of "Te
----
The `LoginModuleName` must match the name of your LoginModule as declared in your login module configuration file (see <>).
-____
[CAUTION]
+====
The name of the realm-name that you declare in `web.xml` must match *exactly* the `Name` field of your `JAASLoginService`.
-____
-
+====
You can declare your `JAASLoginService` in a couple of different ways:
1. If you have more than one webapp that you would like to use the same security infrastructure, then you can declare your `JAASLoginService` in a top-level Jetty xml file as a bean that is added to the `org.eclipse.jetty.server.Server`.
An example:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -104,7 +103,7 @@ An example:
----
2. Alternatively, you can use a `JAASLoginService` with just a specific webapp by creating a link:#deployable-descriptor-file[context xml] file for the webapp, and specifying the `JAASLoginService` in it:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -134,11 +133,10 @@ xyz {
};
----
-____
[CAUTION]
+====
It is imperative that the application name on the first line is *exactly* the same as the `LoginModuleName` of your `JAASLoginService`.
-____
-
+====
You may find it convenient to name this configuration file as `etc/login.conf` because, as we will see below, some of the wiring up for JAAS has been done for you.
===== Step 3
@@ -151,17 +149,16 @@ There are 2 aspects to this:
To accomplish the above, use the Jetty link:#startup-overview[startup] link:#startup-modules[modules mechanism] to add the JAAS link:#startup-modules[module]:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
java -jar start.jar --add-to-start=jaas
-....
+----
-____
[NOTE]
+====
The top level of the distribution does not have the JAAS module enabled by default.
However, there are several link:#demo-webapps-base[demo webapps] - including a JAAS webapp - available in the `demo-base` directory of the distribution which has pre-enabled the JAAS module.
-____
-
+====
Now you will have a file named `start.d/jaas.ini`, which contains:
[source,ini]
@@ -185,7 +182,7 @@ However, should you need to, you can configure:
Here's an example of setting each of these (to their default values):
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
Test JAAS Realm
@@ -220,13 +217,12 @@ As `LoginModules` are free to use their own implementation of the JAAS Principal
* link:{JDURL}/org/eclipse/jetty/jaas/spi/DataSourceLoginModule.html[`org.eclipse.jetty.jaas.spi.DataSourceLoginModule`]
* link:{JDURL}/org/eclipse/jetty/jaas/spi/LdapLoginModule.html[`org.eclipse.jetty.jaas.ldap.LdapLoginModule`]
-____
[NOTE]
+====
Passwords can be stored in clear text, obfuscated or checksummed.
The class link:{JDURL}/org/eclipse/jetty/util/security/Password.html[`org.eclipse.jetty.util.security.Password`] should be used to generate all varieties of passwords,the output from which can be put in to property files or entered into database tables.
See more on this under the Configuration section on link:#configuring-security-secure-passwords[securing passwords].
-____
-
+====
===== JDBCLoginModule
The `JDBCLoginModule` stores user passwords and roles in a database that are accessed via JDBC calls.
@@ -376,7 +372,7 @@ This callback gives you access to all parameters that were passed in the form su
To use it, in the `login()` method of your custom login module, add the `RequestParameterCallback` to the list of callback handlers the login module uses, tell it which params you are interested in, and then get the value of the parameter back.
Here is an example:
-[source, java, subs="{sub-order}"]
+[source, java]
----
public class FooLoginModule extends AbstractLoginModule
diff --git a/jetty-documentation/src/main/asciidoc/configuring/security/jetty-home-and-jetty-base.adoc b/jetty-documentation/src/main/asciidoc/configuring/security/jetty-home-and-jetty-base.adoc
index 96e7f9acb5e4..5358d071ac4b 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/security/jetty-home-and-jetty-base.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/security/jetty-home-and-jetty-base.adoc
@@ -53,16 +53,16 @@ It also assumes you are using `start.ini` to configure your server features.
1. Create a base directory anywhere.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[/home/user]$ mkdir my-base
[/home/user]$ cd my-base
-....
+----
2. Add the modules for SSL, HTTP, and webapp deployment.
Adding modules in this way will append the associated module properties to the `${jetty.base}/start.ini` file.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar --add-to-start=http,https,deploy
INFO : webapp transitively enabled, ini template available with --add-to-start=webapp
@@ -79,11 +79,11 @@ MKDIR : ${jetty.base}/etc
COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
MKDIR : ${jetty.base}/webapps
INFO : Base directory was modified
-....
+----
3. Look at your directory.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ ls -la
total 20
drwxrwxr-x 4 user group 4096 Oct 8 06:55 ./
@@ -91,52 +91,52 @@ drwxr-xr-x 103 user group 4096 Oct 8 06:53 ../
drwxrwxr-x 2 user group 4096 Oct 8 06:55 etc/
-rw-rw-r-- 1 user group 815 Oct 8 06:55 start.ini
drwxrwxr-x 2 user group 4096 Oct 8 06:55 webapps/
-....
+----
4. Copy your WAR files into webapps.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ ls -la
[my-base]$ cp ~/code/project/target/gadget.war webapps/
-....
+----
5. Copy your keystore into place.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ cp ~/code/project/keystore etc/keystore
-....
+----
6. Edit the `start.ini` to configure your SSL settings.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ cat start.ini
-....
+----
7. Initialize module ssl.
+
-....
+----
--module=ssl
-....
+----
8. Define the port to use for secure redirection.
+
-....
+----
jetty.secure.port=8443
-....
+----
9. Set up a demonstration keystore and truststore.
+
-....
+----
jetty.keystore=etc/keystore
jetty.truststore=etc/keystore
-....
+----
10. Set the demonstration passwords.
+
-....
+----
jetty.keystore.password=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
jetty.keymanager.password=OBF:1u2u1wml1z7s1z7a1wnl1u2g
jetty.truststore.password=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
-....
+----
11. Initialize the module server.
+
-....
+----
--module=server
threads.min=10
threads.max=200
@@ -144,24 +144,24 @@ threads.timeout=60000
#jetty.host=myhost.com
jetty.dump.start=false
jetty.dump.stop=false
-....
+----
12. Initialize module http.
+
-....
+----
--module=http
jetty.http.port=8080
http.timeout=30000
-....
+----
13. Initialize module deploy.
+
-....
+----
--module=deploy
-....
+----
Look at the configuration you have at this point.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar --list-config
Java Environment:
@@ -229,17 +229,17 @@ Jetty Active XMLs:
${jetty.home}/etc/jetty-http.xml
${jetty.home}/etc/jetty-ssl.xml
${jetty.home}/etc/jetty-deploy.xml
-....
+----
Now start Jetty.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar
2013-10-08 07:06:55.837:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-08 07:06:55.853:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
2013-10-08 07:06:55.872:INFO:oejs.ServerConnector:main: Started ServerConnector@72974691{HTTP/1.1}{0.0.0.0:8080}
-....
+----
[[reviewing-ssl-config]]
==== Reviewing the Configuration
@@ -261,8 +261,8 @@ Notice that you have `--module=` here and there; you have wrapped up the g
You can see the list of modules:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar --list-modules
Jetty All Available Modules:
@@ -440,7 +440,7 @@ Jetty Active Module Tree:
+ Module: ssl [enabled]
+ Module: webapp [transitive]
+ Module: deploy [enabled]
-....
+----
These are the modules by name, the libraries they bring in, the XML configurations they use, the other modules they depend on (even optional ones), and if the module is in use, where it was enabled.
@@ -448,18 +448,17 @@ While you can manage the list of active modules yourself, it is much easier to e
If you want to start using a new module:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base] $ java -jar ../jetty-distribution-{VERSION}/start.jar --add-to-start=https
-....
+----
This adds the `--module=` lines and associated properties (the parameterized values mentioned above), to your `start.ini`.
-____
[IMPORTANT]
+====
Do not edit the modules and XML files in the `${jetty.home}` directory; there is no need to be moving or copying them unless you want to make your own modules or override the behavior of an existing module.
-____
-
+====
Notice that your `${jetty.base}/start.ini` has no references to the XML files.
That's because the module system and its graph of dependencies now dictate all of the XML files, and their load order.
@@ -482,10 +481,10 @@ For more information on the `start.jar` in 9.1, see xref:start-jar[].
1. Download and unpack Jetty into `/home/user/jetty-distribution-{VERSION}`.
2. Go to your base directory and just use the distribution, no editing.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar
-....
+----
* The Jetty distribution provides, out of the box, the XML configuration files, in this case `jetty-http.xml` and `jetty-ssl.xml`.
These can be found in the `${jetty.home}/etc/` directory.
* We have parameterized all of the configurable values in those XMLs.
@@ -506,10 +505,10 @@ By default, the module system keeps things sane, and transitively includes all d
You can see what the configuration looks like, after all of the modules are resolved, without starting Jetty via:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base] $ java -jar ../jetty-distribution-{VERSION}/start.jar --list-config
-....
+----
Just because the JARs exist on disk does not mean that they are in use.
The configuration controls what is used.
@@ -518,7 +517,7 @@ Use the `--list-config` to see the configuration.
Notice that only a subset of the JARs from the distribution are in use.
The modules you have enabled determine that subset.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[my-base]$ java -jar ~/jetty-distribution-{VERSION}/start.jar --list-config
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/security/openid-support.adoc b/jetty-documentation/src/main/asciidoc/configuring/security/openid-support.adoc
index 76e5fd2238ce..be406b2a2a3d 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/security/openid-support.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/security/openid-support.adoc
@@ -37,7 +37,7 @@ These may look like
===== OpenID Provider Configuration
To enable OpenID support, you first need to activate the `openid` module in your implementation.
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
java -jar {JETTY_HOME}/start.jar --add-to-start=openid
----
@@ -55,7 +55,7 @@ To set the error page, an init param is set at `"org.eclipse.jetty.security.open
Example:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
OPENID
@@ -73,27 +73,27 @@ Example:
If the OpenID Provider allows metadata discovery then you can use.
-[source, java, subs="{sub-order}"]
+[source, java]
----
OpenIdConfiguration openIdConfig = new OpenIdConfiguration(ISSUER, CLIENT_ID, CLIENT_SECRET);
----
Otherwise you can manually enter the necessary information:
-[source, java, subs="{sub-order}"]
+[source, java]
----
OpenIdConfiguration openIdConfig = new OpenIdConfiguration(ISSUER, TOKEN_ENDPOINT, AUTH_ENDPOINT, CLIENT_ID, CLIENT_SECRET);
----
===== Configuring an `OpenIdLoginService`
-[source, java, subs="{sub-order}"]
+[source, java]
----
LoginService loginService = new OpenIdLoginService(openIdConfig);
securityHandler.setLoginService(loginService);
----
===== Configuring an `OpenIdAuthenticator` with `OpenIdConfiguration` and Error Page Redirect
-[source, java, subs="{sub-order}"]
+[source, java]
----
Authenticator authenticator = new OpenIdAuthenticator(openIdConfig, "/error");
securityHandler.setAuthenticator(authenticator);
@@ -106,7 +106,7 @@ servletContextHandler.setSecurityHandler(securityHandler);
Claims about the user can be found using attributes on the session attribute `"org.eclipse.jetty.security.openid.claims"`, and the full response containing the OAuth 2.0 Access Token can be found with the session attribute `"org.eclipse.jetty.security.openid.response"`.
Example:
-[source, java, subs="{sub-order}"]
+[source, java]
----
Map claims = (Map)request.getSession().getAttribute("org.eclipse.jetty.security.openid.claims");
String userId = claims.get("sub");
@@ -127,7 +127,7 @@ If security roles are required they can be configured through a wrapped `LoginSe
This can be configured in XML through `etc/openid-baseloginservice.xml` in the Distribution, or in embedded code using the constructor for the `OpenIdLoginService`.
-[source, java, subs="{sub-order}"]
+[source, java]
----
LoginService wrappedLoginService = ...; // Optional LoginService for Roles
LoginService loginService = new OpenIdLoginService(openIdConfig, wrappedLoginService);
diff --git a/jetty-documentation/src/main/asciidoc/configuring/security/secure-passwords.adoc b/jetty-documentation/src/main/asciidoc/configuring/security/secure-passwords.adoc
index 0f5172fbd9e8..be1a4a185d9b 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/security/secure-passwords.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/security/secure-passwords.adoc
@@ -32,31 +32,31 @@ The class `org.eclipse.jetty.util.security.Password` can be used to generate all
Run it without arguments to see usage instructions:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ java -cp lib/jetty-util-{VERSION}.jar org.eclipse.jetty.util.security.Password
Usage - java org.eclipse.jetty.util.security.Password []
If the password is ?, the user will be prompted for the password
-....
+----
For example, to generate a secured version of the password `password` for the user `username`:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ java -cp ../lib/jetty-util-{VERSION}.jar org.eclipse.jetty.util.security.Password username password
2017-12-13 11:19:27.928:INFO::main: Logging initialized @95ms to org.eclipse.jetty.util.log.StdErrLog
password
OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v
MD5:5f4dcc3b5aa765d61d8327deb882cf99
CRYPT:usjRS48E8ZADM
-....
+----
If using a external tool to create/verify the MD5 hash (such as `md5sum` or `md5`), be sure to verify a carriage return (CR) or new line is not added.
For example:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
//With a CR included
$ echo password | md5sum
286755fad04869ca523320acce0dc6a4 *-
@@ -64,15 +64,14 @@ $ echo password | md5sum
//Using the `-n` option to exclude a new line from being added.
$ echo -n password | md5sum
5f4dcc3b5aa765d61d8327deb882cf99 *-
-....
+----
-____
[IMPORTANT]
+====
When using the `DIGEST` method in tandem with an MD5 hash, you must hash the entire `user:realm:password` string or you will encounter issues with authenticating.
-____
-
-[source, screen, subs="{sub-order}"]
-....
+====
+[source, screen]
+----
$ java -cp ../lib/jetty-util-9.4.7.v20170914.jar org.eclipse.jetty.util.security.Password username username:realm:password
2017-12-13 11:34:33.263:INFO::main: Logging initialized @97ms to org.eclipse.jetty.util.log.StdErrLog
username:realm:password
@@ -82,7 +81,7 @@ CRYPT:usulxZfApLefk
$ echo -n username:realm:password | md5sum
66999343281b2624585fd58cc9d36dfc *-
-....
+----
You can now cut and paste whichever secure version you choose into your configuration file or Java code.
@@ -98,15 +97,14 @@ me:CRYPT:me/ks90E221EY
----
-____
[TIP]
+====
Don't forget to also copy the OBF:, MD5: or CRYPT: prefix on the generated password. It will not be usable by Jetty without it.
-____
-
+====
You can also use obfuscated passwords in Jetty xml files where a plain text password is required.
Here's an example setting the password for a JDBC Datasource with obfuscation:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/security/serving-aliased-files.adoc b/jetty-documentation/src/main/asciidoc/configuring/security/serving-aliased-files.adoc
index 5f0fce6ccb63..fada31b5da67 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/security/serving-aliased-files.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/security/serving-aliased-files.adoc
@@ -72,15 +72,14 @@ ApproveAliases::
AllowSymLinkAliasChecker::
Approve Aliases using the java-7 `Files.readSymbolicLink(path)` and `Path.toRealPath(...)` APIs to check that aliases are valid symbolic links.
-____
[NOTE]
+====
By default, Jetty serves aliased files for implementations running on UNIX as Contexts are created with both the {JDURL}/org/eclipse/jetty/server/handler/AllowSymLinkAliasChecker.html[`AllowSymLinkAliasChecker`] and {JDURL}/org/eclipse/jetty/server/handler/ContextHandler.ApproveNonExistentDirectoryAliases.html[`ApproveNonExistentDirectoryAliases`] alias checkers.
-____
-
+====
An application is free to implement its own Alias checking.
Alias Checkers can be installed in a context via the following XML used in a context deployer file or `WEB-INF/jetty-web.xml`:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/security/setting-port80-access-for-non-root-user.adoc b/jetty-documentation/src/main/asciidoc/configuring/security/setting-port80-access-for-non-root-user.adoc
index 5d8f862e65d5..ddd6cbb8c82a 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/security/setting-port80-access-for-non-root-user.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/security/setting-port80-access-for-non-root-user.adoc
@@ -27,7 +27,7 @@ This page presents several options to access port 80 as a non-root user, includi
On some Linux systems you can use the _ipchains REDIRECT_ mechanism to redirect from one port to another inside the kernel (if `ipchains` is not available, then `iptables` usually is):
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# /sbin/ipchains -I input --proto TCP --dport 80 -j REDIRECT 8080
----
@@ -44,7 +44,7 @@ On many Linux systems you can use the `iptables` REDIRECT mechanism to redirect
You need to add something like the following to the startup scripts or your firewall rules:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# /sbin/iptables -t nat -I PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080
----
@@ -70,43 +70,41 @@ The `http.mod` is enabled by default in the distribution, while the link:#quicks
. Ensure that you have link:#quickstart-changing-jetty-port[changed the http port] to 80 (and link:#quickstart-changing-https-port[changed the https port] to 443 if you are using SSL).
. Enable the `setuid.mod` module:
+
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# java -jar start.jar --add-to-start=setuid
----
+
-____
[NOTE]
+====
The --add-to-start command will enable the setuid module for this and all subsequent executions of jetty.
There are other ways to enable the module, such as for a single execution.
For more information on the alternatives see the section on link:#startup-modules[Managing Startup Modules].
-____
-
+====
. Edit the configuration for the `setuid` module to substitute the `userid` and `groupid` of the user to switch to after starting.
If your server instance has a `${jetty.base/start.d}` directory, this configuration is in the `start.d/setuid.ini` file instead.
Otherwise. this configuration is in the `${jetty.base}start.ini` file.
- Below are the lines to configure:
-+
-[source, text, subs="{sub-order}"]]
+Below are the lines to configure:
+
+[source, text]
----
jetty.startServerAsPrivileged=false
jetty.username=foo
jetty.groupname=bar
jetty.umask=002
----
-+
-____
+
[NOTE]
+====
As well as opening the connectors as `root`, you can also have Jetty start the Server as `root` before changing to the non-`root` user.
-____
-
+====
. A native code library is required to perform user switching.
This code is hosted as part of the https://github.com/eclipse/jetty.toolchain[Jetty ToolChain] project and is released independently from Jetty itself.
You can find the source code in the https://github.com/eclipse/jetty.toolchain/tree/master/jetty-setuid[eclipse/jetty.toolchain/jetty-setuid] project.
Build it locally, which will produce a native library appropriate for the operating system:
+
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# mvn clean install
----
@@ -118,7 +116,7 @@ You may want copy this file into your Jetty distribution's lib directory.
. Start Jetty as the `root` user in your base directory, providing the location of the native library to Java.
Below is an example of how to do it from the command line, assuming you are in the link:#demo-webapps-base[demo-base] directory:
+
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
# sudo java -Djava.library.path=libsetuid-linux -jar $JETTY_HOME/start.jar
----
@@ -129,7 +127,7 @@ Below is an example of how to do it from the command line, assuming you are in t
Solaris 10 provides a User Rights Management framework that can permit users and processes superuser-like abilities:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
usermod -K defaultpriv=basic,net_privaddr myself
----
diff --git a/jetty-documentation/src/main/asciidoc/configuring/security/spnego-support.adoc b/jetty-documentation/src/main/asciidoc/configuring/security/spnego-support.adoc
index 6d816010e1f8..66f84f3ad77b 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/security/spnego-support.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/security/spnego-support.adoc
@@ -29,7 +29,7 @@ There is a substantial amount of configuration and testing required to enable th
To run with SPNEGO enabled the following command line options are required:
-[source,screen, subs="{sub-order}"]
+[source,screen]
----
-Djava.security.krb5.conf=/path/to/jetty/etc/krb5.ini \
-Djava.security.auth.login.config=/path/to/jetty/etc/spnego.conf \
@@ -38,7 +38,7 @@ To run with SPNEGO enabled the following command line options are required:
For debugging the SPNEGO authentication the following options are very helpful:
-[source,screen, subs="{sub-order}"]
+[source,screen]
----
-Dorg.eclipse.jetty.LEVEL=debug \
-Dsun.security.spnego.debug=all
@@ -47,7 +47,7 @@ For debugging the SPNEGO authentication the following options are very helpful:
SPNEGO Authentication must be enabled in the webapp in the following way.
The name of the role will be different for your network.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -75,7 +75,7 @@ A corresponding `UserRealm` needs to be created either programmatically if embed
This is what the configuration within a Jetty xml file would look like.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -91,7 +91,7 @@ This is what the configuration within a Jetty xml file would look like.
This is what the configuration within a context xml file would look like.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -124,14 +124,14 @@ To do this use a process similar to this:
On the Windows Active Domain Controller run:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ setspn -A HTTP/linux.mortbay.org ADUser
----
To create the keytab file use the following process:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ ktpass -out c:\dir\krb5.keytab -princ HTTP/linux.mortbay.org@MORTBAY.ORG -mapUser ADUser -mapOp set -pass ADUserPWD -crypto RC4-HMAC-NT -pType KRB5_NT_PRINCIPAL
----
diff --git a/jetty-documentation/src/main/asciidoc/development/ant/jetty-ant.adoc b/jetty-documentation/src/main/asciidoc/development/ant/jetty-ant.adoc
index b53fe52cffae..a10715cad120 100644
--- a/jetty-documentation/src/main/asciidoc/development/ant/jetty-ant.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/ant/jetty-ant.adoc
@@ -23,7 +23,7 @@ The Ant Jetty plugin is a part of Jetty 9 under the `jetty-ant` module.
This plugin makes it possible to start a Jetty web server directly from the Ant build script, and to embed the Jetty web server inside your build process.
Its purpose is to provide almost the same functionality as the Jetty plugin for Maven: dynamic application reloading, working directly on web application sources, and tightly integrating with the build system.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -51,7 +51,7 @@ Now you're ready to edit or create your Ant `build.xml` file.
Begin with an empty `build.xml`:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -60,7 +60,7 @@ Begin with an empty `build.xml`:
Add a `` that imports all available Jetty tasks:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -76,7 +76,7 @@ Add a `` that imports all available Jetty tasks:
Now you are ready to add a new target for running Jetty:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -100,10 +100,10 @@ This is the minimal configuration you need. You can now start Jetty on the defau
At the command line enter:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> ant jetty.run
-....
+----
==== Configuring the Jetty Container
@@ -113,7 +113,7 @@ ports and connectors:::
To configure the port that Jetty starts on you need to define a connector.
First you need to configure a `` for the Connector class and then define the connector in the Jetty tags:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -138,17 +138,16 @@ ports and connectors:::
----
+
-____
[TIP]
+====
You can set the port to 0, which starts the Jetty server connector on an arbitrary available port.
You can then access these values from system properties `jetty.ant.server.port` and `jetty.ant.server.host`.
-____
-
+====
login services:::
If your web application requires authentication and authorization services, you can configure these on the Jetty container.
Here's an example of how to set up an link:{JDURL}/org/eclipse/jetty/security/HashLoginService.html[org.eclipse.jetty.security.HashLoginService]:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -176,7 +175,7 @@ request log:::
The `requestLog` option allows you to specify a request logger for the Jetty instance.
You can either use the link:{JDURL}/org/eclipse/jetty/server/NCSARequestLog.html[org.eclipse.jetty.server.NCSARequestLog] class, or supply the name of your custom class:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -197,7 +196,7 @@ request log:::
temporary directory:::
You can configure a directory as a temporary file store for uses such as expanding files and compiling JSPs by supplying the `tempDirectory` option:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -220,7 +219,7 @@ other context handlers:::
You can specify these other context handlers using the `` element.
You need to supply a `` for it before you can use it:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -249,7 +248,7 @@ system properties:::
As a convenience, you can configure system properties by using the `` element.
Be aware that, depending on the purpose of the system property, setting it from within the Ant execution may mean that it is evaluated too late, as the JVM evaluates some system properties on entry.
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -273,7 +272,7 @@ system properties:::
jetty XML file:::
If you have a lot of configuration to apply to the Jetty container, it can be more convenient to put it into a standard Jetty XML configuration file and have the Ant plugin apply it before starting Jetty:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -297,7 +296,7 @@ scanning for changes:::
The `scanIntervalSeconds` option controls how frequently the `` task scans your web application/WAR file for changes.
The default value of `0` disables scanning. Here's an example where Jetty checks for changes every five seconds:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -323,7 +322,7 @@ stopping:::
The `` task sends this stop message.
You can also optionally provide a `stopWait` value (in seconds), which is the length of time the `` task waits for confirmation that the stop succeeded:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -348,10 +347,10 @@ stopping:::
+
To stop jetty via Ant, enter:
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> ant jetty.stop
-....
+----
execution without pausing ant:::
@@ -361,7 +360,7 @@ execution without pausing ant:::
This defaults to `false`. For `true`, Ant continues to execute after starting Jetty.
If Ant exits, so does Jetty. Understand that this option does _not_ fork a new process for Jetty.
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -385,7 +384,7 @@ execution without pausing ant:::
Add a `` for the `org.eclipse.jetty.ant.AntWebAppContext` class with name __webApp__, then add a `` element to `` to describe your web application.
The following example deploys a web application that is expanded in the local directory `foo/` to context path ` / `:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -412,7 +411,7 @@ deploying a WAR file:::
It is not necessary to expand the web application into a directory.
It is fine to deploy it as a WAR file:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -438,7 +437,7 @@ deploying a WAR file:::
deploying more than one web application:::
You can also deploy more than one web application:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -473,7 +472,7 @@ class, you can configure it by adding attributes of the same name
Here's an example that specifies the location of the `web.xml` file (equivalent to method link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html#setDescriptor%28java.lang.String%29[`AntWebAppContext.setDescriptor()`]) and the web application's temporary directory (equivalent to method link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html#setTempDirectory%28java.io.File%29[`AntWebAppContext.setTempDirectory()`]):
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -501,7 +500,7 @@ Other extra configuration options for the AntWebAppContext include:
extra classes and Jars:::
If your web application's classes and Jars do not reside inside `WEB-INF` of the resource base directory, you can use the and elements to tell Ant where to find them. Here's an example:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -538,7 +537,7 @@ context attributes:::
For convenience, the Ant plugin permits you to configure these directly in the build file.
Here's an example:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -567,7 +566,7 @@ context attributes:::
`jetty-env.xml` file:::
If you are using features such as link:#configuring_jndi[JNDI] with your web application, you may need to configure a link:#using_jndi[`WEB-INF/jetty-env.xml`] file to define resources. If the structure of your web application project is such that the source of `jetty-env.xml` file resides somewhere other than `WEB-INF`, you can use the `jettyEnvXml` attribute to tell Ant where to find it:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -596,7 +595,7 @@ context XML file:::
In this case, you can use a standard context XML configuration file which the Ant plugin applies to your web application before it is deployed.
Be aware that the settings from the context XML file _override_ those of the attributes and nested elements you defined in the build file.
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
project name="Jetty-Ant integration test" basedir=".">
diff --git a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-api.adoc b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-api.adoc
index eee548a7c00a..cea1ca578c51 100644
--- a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-api.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-api.adoc
@@ -24,7 +24,7 @@
The simple way to perform a HTTP request is the following:
-[source, java, subs="{sub-order}"]
+[source, java]
----
ContentResponse response = httpClient.GET("http://domain.com/path?query");
----
@@ -36,7 +36,7 @@ The content length is limited by default to 2 MiB; for larger content see xref:h
If you want to customize the request, for example by issuing a `HEAD` request instead of a `GET`, and simulating a browser user agent, you can do it in this way:
-[source, java, subs="{sub-order}"]
+[source, java]
----
ContentResponse response = httpClient.newRequest("http://domain.com/path?query")
.method(HttpMethod.HEAD)
@@ -46,7 +46,7 @@ ContentResponse response = httpClient.newRequest("http://domain.com/path?query")
This is a shorthand for:
-[source, java, subs="{sub-order}"]
+[source, java]
----
Request request = httpClient.newRequest("http://domain.com/path?query");
request.method(HttpMethod.HEAD);
@@ -59,7 +59,7 @@ When the request object is customized, you call `request.send()` that produces t
Simple `POST` requests also have a shortcut method:
-[source, java, subs="{sub-order}"]
+[source, java]
----
ContentResponse response = httpClient.POST("http://domain.com/entity/1")
.param("p", "value")
@@ -73,7 +73,7 @@ Following redirects is a feature that you can enable/disable on a per-request ba
File uploads also require one line, and make use of JDK 7′s `java.nio.file` classes:
-[source, java, subs="{sub-order}"]
+[source, java]
----
ContentResponse response = httpClient.newRequest("http://domain.com/upload")
.method(HttpMethod.POST)
@@ -83,7 +83,7 @@ ContentResponse response = httpClient.newRequest("http://domain.com/upload")
It is possible to impose a total timeout for the request/response conversation using the `Request.timeout(...)` method as follows:
-[source, java, subs="{sub-order}"]
+[source, java]
----
ContentResponse response = httpClient.newRequest("http://domain.com/path?query")
.timeout(5, TimeUnit.SECONDS)
@@ -123,7 +123,7 @@ When the request and the response are both fully processed, the thread that fini
A simple asynchronous `GET` request that discards the response content can be written in this way:
-[source, java, subs="{sub-order}"]
+[source, java]
----
httpClient.newRequest("http://domain.com/path")
.send(new Response.CompleteListener()
@@ -140,7 +140,7 @@ Method `Request.send(Response.CompleteListener)` returns `void` and does not blo
You can write the same code using JDK 8′s lambda expressions:
-[source, java, subs="{sub-order}"]
+[source, java]
----
httpClient.newRequest("http://domain.com/path")
.send(result -> { /* Your logic here */ });
@@ -148,7 +148,7 @@ httpClient.newRequest("http://domain.com/path")
You can impose a total timeout for the request/response conversation in the same way used by the synchronous API:
-[source, java, subs="{sub-order}"]
+[source, java]
----
httpClient.newRequest("http://domain.com/path")
.timeout(3, TimeUnit.SECONDS)
@@ -159,7 +159,7 @@ The example above will impose a total timeout of 3 seconds on the request/respon
The HTTP client APIs use listeners extensively to provide hooks for all possible request and response events, and with JDK 8′s lambda expressions they are even more fun to use:
-[source, java, subs="{sub-order}"]
+[source, java]
----
httpClient.newRequest("http://domain.com/path")
// Add request hooks
@@ -191,7 +191,7 @@ Jetty's HTTP client provides a number of utility classes off the shelf to handle
You can provide request content as `String`, `byte[]`, `ByteBuffer`, `java.nio.file.Path`, `InputStream`, and provide your own implementation of `org.eclipse.jetty.client.api.ContentProvider`.
Here’s an example that provides the request content using `java.nio.file.Paths`:
-[source, java, subs="{sub-order}"]
+[source, java]
----
ContentResponse response = httpClient.newRequest("http://domain.com/upload")
.method(HttpMethod.POST)
@@ -201,7 +201,7 @@ ContentResponse response = httpClient.newRequest("http://domain.com/upload")
This is equivalent to using the `PathContentProvider` utility class:
-[source, java, subs="{sub-order}"]
+[source, java]
----
ContentResponse response = httpClient.newRequest("http://domain.com/upload")
.method(HttpMethod.POST)
@@ -211,7 +211,7 @@ ContentResponse response = httpClient.newRequest("http://domain.com/upload")
Alternatively, you can use `FileInputStream` via the `InputStreamContentProvider` utility class:
-[source, java, subs="{sub-order}"]
+[source, java]
----
ContentResponse response = httpClient.newRequest("http://domain.com/upload")
.method(HttpMethod.POST)
@@ -223,7 +223,7 @@ Since `InputStream` is blocking, then also the send of the request will block if
If you have already read the content in memory, you can pass it as a `byte[]` using the `BytesContentProvider` utility class:
-[source, java, subs="{sub-order}"]
+[source, java]
----
byte[] bytes = ...;
ContentResponse response = httpClient.newRequest("http://domain.com/upload")
@@ -234,7 +234,7 @@ ContentResponse response = httpClient.newRequest("http://domain.com/upload")
If the request content is not immediately available, but your application will be notified of the content to send, you can use `DeferredContentProvider` in this way:
-[source, java, subs="{sub-order}"]
+[source, java]
----
DeferredContentProvider content = new DeferredContentProvider();
httpClient.newRequest("http://domain.com/upload")
@@ -270,7 +270,7 @@ This allows fine-grained control of the request/response conversation: for examp
Another way to provide request content is by using an `OutputStreamContentProvider`,
which allows applications to write request content when it is available to the `OutputStream` provided by `OutputStreamContentProvider`:
-[source, java, subs="{sub-order}"]
+[source, java]
----
OutputStreamContentProvider content = new OutputStreamContentProvider();
@@ -306,7 +306,7 @@ The first way is to buffer the response content in memory; this is done when usi
If you want to control the length of the response content (for example limiting to values smaller than the default of 2 MiB), then you can use a `org.eclipse.jetty.client.util.FutureResponseListener` in this way:
-[source, java, subs="{sub-order}"]
+[source, java]
----
Request request = httpClient.newRequest("http://domain.com/path");
@@ -322,7 +322,7 @@ If the response content length is exceeded, the response will be aborted, and an
If you are using the asynchronous APIs (see xref:http-client-async[]), you can use the `BufferingResponseListener` utility class:
-[source, java, subs="{sub-order}"]
+[source, java]
----
httpClient.newRequest("http://domain.com/path")
// Buffer response content up to 8 MiB
@@ -344,7 +344,7 @@ The second way is the most efficient (because it avoids content copies) and allo
In the example below, `Response.Listener.Adapter` is a class that implements both `Response.ContentListener` and `Response.CompleteListener` and can be passed to `Request.send()`.
Jetty's HTTP client will invoke the `onContent()` method zero or more times (until there is content), and finally invoke the `onComplete()` method.
-[source, java, subs="{sub-order}"]
+[source, java]
----
httpClient .newRequest("http://domain.com/path")
.send(new Response.Listener.Adapter()
@@ -359,7 +359,7 @@ httpClient .newRequest("http://domain.com/path")
The third way allows you to wait for the response and then stream the content using the `InputStreamResponseListener` utility class:
-[source, java, subs="{sub-order}"]
+[source, java]
----
InputStreamResponseListener listener = new InputStreamResponseListener();
diff --git a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-authentication.adoc b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-authentication.adoc
index 3e5dfcc9aa1d..708a088c0401 100644
--- a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-authentication.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-authentication.adoc
@@ -23,7 +23,7 @@ Jetty's HTTP client supports the `BASIC` and `DIGEST` authentication mechanisms
You can configure authentication credentials in the HTTP client instance as follows:
-[source, java, subs="{sub-order}"]
+[source, java]
----
URI uri = new URI("http://domain.com/secure");
String realm = "MyRealm";
@@ -61,14 +61,14 @@ The application does not receive events related to the response with code 401, t
Successful authentications are cached, but it is possible to clear them in order to force authentication again:
-[source, java, subs="{sub-order}"]
+[source, java]
----
httpClient.getAuthenticationStore().clearAuthenticationResults();
----
Authentications may be preempted to avoid the additional roundtrip due to the server challenge in this way:
-[source, java, subs="{sub-order}"]
+[source, java]
----
AuthenticationStore auth = httpClient.getAuthenticationStore();
URI uri = URI.create("http://domain.com/secure");
@@ -79,7 +79,7 @@ In this way, requests for the given URI are enriched by `HttpClient` immediately
It is also possible to preempt the authentication for a single request only, in this way:
-[source, java, subs="{sub-order}"]
+[source, java]
----
URI uri = URI.create("http://domain.com/secure");
Authentication.Result authn = new BasicAuthentication.BasicResult(uri, "username", "password")
diff --git a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-cookie.adoc b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-cookie.adoc
index 53fc289b324b..93ddf646f7de 100644
--- a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-cookie.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-cookie.adoc
@@ -25,7 +25,7 @@ When new requests are made, the cookie store is consulted and if there are match
Applications can programmatically access the cookie store to find the cookies that have been set:
-[source, java, subs="{sub-order}"]
+[source, java]
----
CookieStore cookieStore = httpClient.getCookieStore();
List cookies = cookieStore.get(URI.create("http://domain.com/path"));
@@ -33,7 +33,7 @@ List cookies = cookieStore.get(URI.create("http://domain.com/path"))
Applications can also programmatically set cookies as if they were returned from a HTTP response:
-[source, java, subs="{sub-order}"]
+[source, java]
----
CookieStore cookieStore = httpClient.getCookieStore();
HttpCookie cookie = new HttpCookie("foo", "bar");
@@ -45,7 +45,7 @@ cookieStore.add(URI.create("http://domain.com"), cookie);
Cookies may be added only for a particular request:
-[source, java, subs="{sub-order}"]
+[source, java]
----
ContentResponse response = httpClient.newRequest("http://domain.com/path")
.cookie(new HttpCookie("foo", "bar"))
@@ -54,7 +54,7 @@ ContentResponse response = httpClient.newRequest("http://domain.com/path")
You can remove cookies that you do not want to be sent in future HTTP requests:
-[source, java, subs="{sub-order}"]
+[source, java]
----
CookieStore cookieStore = httpClient.getCookieStore();
URI uri = URI.create("http://domain.com");
@@ -65,14 +65,14 @@ for (HttpCookie cookie : cookies)
If you want to totally disable cookie handling, you can install a `HttpCookieStore.Empty` instance in this way:
-[source, java, subs="{sub-order}"]
+[source, java]
----
httpClient.setCookieStore(new HttpCookieStore.Empty());
----
You can enable cookie filtering by installing a cookie store that performs the filtering logic in this way:
-[source, java, subs="{sub-order}"]
+[source, java]
----
httpClient.setCookieStore(new GoogleOnlyCookieStore());
@@ -94,14 +94,14 @@ Jetty is compliant with link:https://tools.ietf.org/html/rfc6265[RFC6265], and a
Previously, Version=1 cookies defined in link:https://tools.ietf.org/html/rfc2109[RFC2109] (and continued in link:https://tools.ietf.org/html/rfc2965[RFC2965]) allowed for special/reserved characters to be enclosed within double quotes when declared in a `Set-Cookie` response header:
-[source, java, subs="{sub-order}"]
+[source, java]
----
Set-Cookie: foo="bar;baz";Version=1;Path="/secur"
----
This was added to the HTTP Response header as follows:
-[source, java, subs="{sub-order}"]
+[source, java]
----
Cookie cookie = new Cookie("foo", "bar;baz");
cookie.setPath("/secur");
@@ -111,7 +111,7 @@ response.addCookie(cookie);
The introduction of RFC6265 has rendered this approach no longer possible; users are now required to encode cookie values that use these special characters.
This can be done utilizing `javax.servlet.http.Cookie` as follows:
-[source, java, subs="{sub-order}"]
+[source, java]
----
Cookie cookie = new Cookie("foo", URLEncoder.encode("bar;baz", "utf-8"));
----
diff --git a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-intro.adoc b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-intro.adoc
index 8c1e949e1566..75b64b951069 100644
--- a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-intro.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-intro.adoc
@@ -54,7 +54,7 @@ it provides you with the responses to the requests you make.
In order to use `HttpClient`, you must instantiate it, configure it, and then start it:
-[source, java, subs="{sub-order}"]
+[source, java]
----
// Instantiate HttpClient
HttpClient httpClient = new HttpClient();
@@ -78,7 +78,7 @@ When you create a `HttpClient` instance using the parameterless constructor, you
In order to perform HTTPS requests, you should create first a link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.Client.html[`SslContextFactory.Client`], configure it, and pass it to the `HttpClient` constructor.
When created with a `SslContextFactory`, the `HttpClient` will be able to perform both HTTP and HTTPS requests to any domain.
-[source, java, subs="{sub-order}"]
+[source, java]
----
// Instantiate and configure the SslContextFactory
SslContextFactory.Client sslContextFactory = new SslContextFactory.Client();
@@ -97,7 +97,7 @@ httpClient.start();
It is recommended that when your application stops, you also stop the `HttpClient` instance (or instances) that you are using.
-[source, java, subs="{sub-order}"]
+[source, java]
----
httpClient.stop();
----
diff --git a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-proxy.adoc b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-proxy.adoc
index 96844a29f8f7..22c223164903 100644
--- a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-proxy.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-proxy.adoc
@@ -26,7 +26,7 @@ Other implementations may be written by subclassing `ProxyConfiguration.Proxy`.
The following is a typical configuration:
-[source, java, subs="{sub-order}"]
+[source, java]
----
ProxyConfiguration proxyConfig = httpClient.getProxyConfiguration();
HttpProxy proxy = new HttpProxy("proxyHost", proxyPort);
@@ -51,7 +51,7 @@ Jetty's HTTP client support proxy authentication in the same way it supports lin
In the example below, the proxy requires Basic authentication, but the server requires Digest authentication, and therefore:
-[source, java, subs="{sub-order}"]
+[source, java]
----
URI proxyURI = new URI("http://proxy.net:8080");
URI serverURI = new URI("http://domain.com/secure");
diff --git a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-transport.adoc b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-transport.adoc
index 173d3528c6e3..705c49de8fcc 100644
--- a/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-transport.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/clients/http/http-client-transport.adoc
@@ -30,7 +30,7 @@ This allows them to write their logic against a high-level API that hides the de
The most common protocol format is HTTP/1.1, a text-based protocol with lines separated by `\r\n`:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
GET /index.html HTTP/1.1\r\n
Host: domain.com\r\n
@@ -40,7 +40,7 @@ Host: domain.com\r\n
However, the same request can be made using FastCGI, a binary protocol:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
x01 x01 x00 x01 x00 x08 x00 x00
x00 x01 x01 x00 x00 x00 x00 x00
@@ -58,7 +58,7 @@ Similarly, HTTP/2 is a binary protocol that transports the same information in a
HTTP/1.1 is the default transport.
-[source, java, subs="{sub-order}"]
+[source, java]
----
// No transport specified, using default.
HttpClient client = new HttpClient();
@@ -67,7 +67,7 @@ client.start();
If you want to customize the HTTP/1.1 transport, you can explicitly configure `HttpClient` in this way:
-[source, java, subs="{sub-order}"]
+[source, java]
----
int selectors = 1;
HttpClientTransportOverHTTP transport = new HttpClientTransportOverHTTP(selectors);
@@ -82,7 +82,7 @@ The example above allows you to customize the number of NIO selectors that `Http
The HTTP/2 transport can be configured in this way:
-[source, java, subs="{sub-order}"]
+[source, java]
----
HTTP2Client h2Client = new HTTP2Client();
h2Client.setSelectors(1);
@@ -100,7 +100,7 @@ client.start();
The FastCGI transport can be configured in this way:
-[source, java, subs="{sub-order}"]
+[source, java]
----
int selectors = 1;
String scriptRoot = "/var/www/wordpress";
diff --git a/jetty-documentation/src/main/asciidoc/development/continuations/continuations-patterns.adoc b/jetty-documentation/src/main/asciidoc/development/continuations/continuations-patterns.adoc
index 22107b3651b1..07af69c5bea8 100644
--- a/jetty-documentation/src/main/asciidoc/development/continuations/continuations-patterns.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/continuations/continuations-patterns.adoc
@@ -24,7 +24,7 @@
The suspend/resume style is used when a servlet and/or filter is used to generate the response after an asynchronous wait that is terminated by an asynchronous handler.
Typically a request attribute is used to pass results and to indicate if the request has already been suspended.
-[source, java, subs="{sub-order}"]
+[source, java]
----
void doGet(HttpServletRequest request, HttpServletResponse response)
{
@@ -69,7 +69,7 @@ This style is very good when the response needs the facilities of the servlet co
The suspend/complete style is used when an asynchronous handler is used to generate the response:
-[source, java, subs="{sub-order}"]
+[source, java]
----
void doGet(HttpServletRequest request, HttpServletResponse response)
{
diff --git a/jetty-documentation/src/main/asciidoc/development/continuations/continuations-using.adoc b/jetty-documentation/src/main/asciidoc/development/continuations/continuations-using.adoc
index 644354e47fc3..a61a2f2a285e 100644
--- a/jetty-documentation/src/main/asciidoc/development/continuations/continuations-using.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/continuations/continuations-using.adoc
@@ -33,7 +33,7 @@ The link:{JDURL}/org/eclipse/jetty/continuation/ContinuationSupport.html[Continu
To suspend a request, the suspend method can be called on the continuation:
-[source, java, subs="{sub-order}"]
+[source, java]
----
void doGet(HttpServletRequest request, HttpServletResponse response)
{
@@ -62,7 +62,7 @@ If an exception is desirable (to bypass code that is unaware of continuations an
Once an asynchronous event has occurred, the continuation can be resumed:
-[source, java, subs="{sub-order}"]
+[source, java]
----
void myAsyncCallback(Object results)
{
@@ -80,7 +80,7 @@ Continuation resume is analogous to Servlet 3.0 `AsyncContext.dispatch()`.
As an alternative to resuming a request, an asynchronous handler may write the response itself. After writing the response, the handler must indicate the request handling is complete by calling the complete method:
-[source, java, subs="{sub-order}"]
+[source, java]
----
void myAsyncCallback(Object results)
{
@@ -95,7 +95,7 @@ After complete is called, the container schedules the response to be committed
An application may monitor the status of a continuation by using a ContinuationListener:
-[source, java, subs="{sub-order}"]
+[source, java]
----
void doGet(HttpServletRequest request, HttpServletResponse response)
{
diff --git a/jetty-documentation/src/main/asciidoc/development/embedding/embedded-examples.adoc b/jetty-documentation/src/main/asciidoc/development/embedding/embedded-examples.adoc
index ad4784e22897..e13c6cd48f3d 100644
--- a/jetty-documentation/src/main/asciidoc/development/embedding/embedded-examples.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/embedding/embedded-examples.adoc
@@ -22,12 +22,11 @@
Jetty has a rich history of being embedded into a wide variety of applications.
In this section we will walk you through a number of our simple examples under our embedded-jetty-examples project in our git repository.
-____
[IMPORTANT]
+====
These files are pulled directly from our git repository when this document is generated.
If the line numbers do not line up feel free to fix this documentation in github and give us a pull request, or at least open an issue to notify us of the discrepancy.
-____
-
+====
include::examples/embedded-file-server.adoc[]
include::examples/embedded-split-file-server.adoc[]
include::examples/embedded-many-connectors.adoc[]
@@ -42,7 +41,7 @@ This example is very similar to the one in the previous section, although it ena
As of jetty-9.2, we use the JSP engine from Apache, which relies on a Servlet Specification 3.1 style `ServletContainerInitializer` to initialize itself.
To get this to work with Jetty, you need to enable annotations processing, as shown in this example code:
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneWebAppWithJsp.java[]
@@ -56,7 +55,7 @@ After you have started things up you should be able to navigate to http://localh
To use this example in your project, you will need the following Maven dependencies declared, in addition to those from the previous section:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/development/embedding/embedding-jetty.adoc b/jetty-documentation/src/main/asciidoc/development/embedding/embedding-jetty.adoc
index 797a4aab6ee1..9ba569557d0d 100644
--- a/jetty-documentation/src/main/asciidoc/development/embedding/embedding-jetty.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/embedding/embedding-jetty.adoc
@@ -80,7 +80,7 @@ The handler sets the response status, content-type, and marks the request as han
To allow a Handler to handle HTTP requests, you must add it to a Server instance.
The following code from OneHandler.java shows how a Jetty server can use the HelloWorld handler:
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneHandler.java[]
----
@@ -117,14 +117,14 @@ For example, when a `ContextHandler` calls some application listeners to inform
The `HandlerWrapper` is specialized to the link:{JDURL}/org/eclipse/jetty/server/handler/ScopedHandler.html[`ScopedHandler`] abstract class, which supports a daisy chain of scopes.
For example if a `ServletHandler` is nested within a `ContextHandler`, the order and nesting of execution of methods is:
-....
+----
Server.handle(...)
ContextHandler.doScope(...)
ServletHandler.doScope(...)
ContextHandler.doHandle(...)
ServletHandler.doHandle(...)
SomeServlet.service(...)
-....
+----
Thus when the `ContextHandler` handles the request, it does so within the scope the `ServletHandler` has established.
@@ -132,7 +132,7 @@ Thus when the `ContextHandler` handles the request, it does so within the scope
The link:{JDURL}/org/eclipse/jetty/embedded/FileServer.html[FileServer example] shows how you can use a `ResourceHandler` to serve static content from the current working directory:
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/FileServer.java[]
----
@@ -149,7 +149,7 @@ However, often when embedding Jetty it is desirable to explicitly instantiate an
The following example, link:{JDURL}/org/eclipse/jetty/embedded/OneConnector.html[OneConnector.java],
instantiates, configures, and adds a single HTTP connector instance to the server:
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneConnector.java[]
----
@@ -173,7 +173,7 @@ It uses standard path mappings to match a Servlet to a request; sets the request
The link:{JDURL}/org/eclipse/jetty/embedded/MinimalServlets.html[MinimalServlets example] creates a `ServletHandler` instance and configures a single HelloServlet:
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/MinimalServlets.java[]
----
@@ -191,7 +191,7 @@ Requests that match the context path have their path methods updated accordingly
The following link:{JDURL}/org/eclipse/jetty/embedded/OneContext.html[OneContext example] shows a context being established that wraps the link:{JDURL}/org/eclipse/jetty/embedded/HelloHandler.html[HelloHandler]:
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneContext.java[]
----
@@ -199,7 +199,7 @@ include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/One
When many contexts are present, you can embed a `ContextHandlerCollection` to efficiently examine a request URI to then select the matching `ContextHandler`(s) for the request.
The link:{JDURL}/org/eclipse/jetty/embedded/ManyContexts.html[ManyContexts example] shows how many such contexts you can configure:
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ManyContexts.java[]
----
@@ -209,7 +209,7 @@ include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/Man
A link:{JDURL}/org/eclipse/jetty/servlet/ServletContextHandler.html[`ServletContextHandler`] is a specialization of `ContextHandler` with support for standard sessions and Servlets.
The following link:{JDURL}/org/eclipse/jetty/embedded/OneServletContext.html[OneServletContext example] instantiates a link:{JDURL}/org/eclipse/jetty/servlet/DefaultServlet.html[`DefaultServlet`] to server static content from /tmp/ and a `DumpServlet` that creates a session and dumps basic details about the request:
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneServletContext.java[]
----
@@ -220,7 +220,7 @@ A link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`] is a
The following link:{JDURL}/org/eclipse/jetty/embedded/OneWebApp.html[OneWebApp example] configures the Jetty test webapp.
Web applications can use resources the container provides, and in this case a `LoginService` is needed and also configured:
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneWebApp.java[]
----
@@ -241,7 +241,7 @@ The link:{GITBROWSEURL}/examples/embedded/src/main/java/org/eclipse/jetty/embedd
* link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-lowresources.xml[jetty-lowresources.xml]
* link:{GITBROWSEURL}/tests/test-webapps/test-jetty-webapp/src/main/config/etc/test-realm.xml[test-realm.xml]
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/LikeJettyXml.java[]
----
diff --git a/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-file-server.adoc b/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-file-server.adoc
index 9f39dacd0c86..9ac9ef39b7c3 100644
--- a/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-file-server.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-file-server.adoc
@@ -24,7 +24,7 @@ It is perfectly suitable for test cases where you need an actual web server to o
Note that this does not have any logic for caching of files, either within the server or setting the appropriate headers on the response.
It is simply a few lines that illustrate how easy it is to serve out some files.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/FileServer.java[]
@@ -38,7 +38,7 @@ After you have started things up you should be able to navigate to http://localh
To use this example in your project you will need the following Maven dependencies declared.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
diff --git a/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-many-connectors.adoc b/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-many-connectors.adoc
index ecd85369cac5..7010d0e18a4e 100644
--- a/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-many-connectors.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-many-connectors.adoc
@@ -22,7 +22,7 @@
This example shows how to configure Jetty to use multiple connectors, specifically so it can process both http and https requests.
Since the meat of this example is the server and connector configuration it only uses a simple HelloHandler but this example should be easily merged with other examples like those deploying servlets or webapps.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ManyConnectors.java[]
@@ -38,7 +38,7 @@ See link:http://docs.oracle.com/javase/1.5.0/docs/api/java/lang/Thread.html#join
To use this example in your project you will need the following Maven dependencies declared.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-minimal-servlet.adoc b/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-minimal-servlet.adoc
index f322c4875d14..ccd21a0527ae 100644
--- a/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-minimal-servlet.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-minimal-servlet.adoc
@@ -24,7 +24,7 @@ Note that this is strictly a servlet, not a servlet in the context of a web appl
This is purely just a servlet deployed and mounted on a context and able to process requests.
This example is excellent for situations where you have a simple servlet that you need to unit test, just mount it on a context and issue requests using your favorite http client library (like our Jetty client found in xref:http-client[]).
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/MinimalServlets.java[]
@@ -43,7 +43,7 @@ After you have started things up you should be able to navigate to http://localh
To use this example in your project you will need the following Maven dependencies declared.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-one-webapp.adoc b/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-one-webapp.adoc
index cf296730115f..29413a95dc49 100644
--- a/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-one-webapp.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-one-webapp.adoc
@@ -23,7 +23,7 @@ This example shows how to deploy a simple webapp with an embedded instance of Je
This is useful when you want to manage the lifecycle of a server programmatically, either within a production application or as a simple way to deploying and debugging a full scale application deployment.
In many ways it is easier then traditional deployment since you control the classpath yourself, making this easy to wire up in a test case in Maven and issue requests using your favorite http client library (like our Jetty client found in xref:http-client[]).
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneWebApp.java[]
@@ -37,7 +37,7 @@ After you have started things up you should be able to navigate to http://localh
To use this example in your project you will need the following Maven dependencies declared.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-secured-hello-handler.adoc b/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-secured-hello-handler.adoc
index 111791db4a17..5a2ddf5e0f07 100644
--- a/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-secured-hello-handler.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-secured-hello-handler.adoc
@@ -24,7 +24,7 @@ We have a simple Hello Handler that just return a greeting but add on the restri
Another thing to remember is that this example uses the `ConstraintSecurityHandler` which is what supports the security mappings inside of the servlet api, it could be easier to show just the `SecurityHandler` usage, but the constraint provides more configuration power.
If you don't need that you can drop the Constraint bits and use just the `SecurityHandler`.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/SecuredHelloHandler.java[]
@@ -46,7 +46,7 @@ include::{SRCDIR}/examples/embedded/src/test/resources/realm.properties[]
To use this example in your project you will need the following Maven dependencies declared.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-split-file-server.adoc b/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-split-file-server.adoc
index d2b5d38b1208..59e9dc575f80 100644
--- a/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-split-file-server.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/embedding/examples/embedded-split-file-server.adoc
@@ -21,7 +21,7 @@
This example builds on the link:#emebedded-file-server[Simple File Server] to show how chaining multiple `ResourceHandlers` together can let you aggregate multiple directories to serve content on a single path and how you can link these together with `ContextHandlers`.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/SplitFileServer.java[]
@@ -38,7 +38,7 @@ Any requests for files will be looked for in the first resource handler, then th
To use this example as is in your project you will need the following maven dependencies declared.
We would recommend not using the toolchain dependency in your actual application.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/development/embedding/jetty-helloworld.adoc b/jetty-documentation/src/main/asciidoc/development/embedding/jetty-helloworld.adoc
index 23ab40149993..cde3c3f8ab79 100644
--- a/jetty-documentation/src/main/asciidoc/development/embedding/jetty-helloworld.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/embedding/jetty-helloworld.adoc
@@ -28,26 +28,24 @@ Jetty is decomposed into many jars and dependencies to achieve a minimal footpri
Typically it is best to use something like link:#jetty-maven-helloworld[Maven] to manage jars, however this tutorial uses an aggregate Jar that contains all of the required Jetty classes in one Jar.
You can manually download the aggregate link:https://repo1.maven.org/maven2/org/eclipse/jetty/aggregate/jetty-all/{VERSION}/jetty-all-{VERSION}-uber.jar[`jetty-all.jar`] using `curl` or a browser.
-____
[NOTE]
+====
The central Maven repository has started to aggressively reject/deny access to the repository from the `wget` command line tool (due to abusive use of the tool by some groups).
The administrators of the central maven repository have stated that the recommended command line download tool is now curl.
-____
-
-____
+====
[IMPORTANT]
+====
The `jetty-all` jar referenced in this section is for example purposes only and should not be used outside of this context.
Please consider using link:#jetty-maven-helloworld[Maven] to manage your project dependencies.
-____
-
+====
Use curl as follows:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> mkdir Demo
> cd Demo
> curl -o jetty-all-uber.jar https://repo1.maven.org/maven2/org/eclipse/jetty/aggregate/jetty-all/{VERSION}/jetty-all-{VERSION}-uber.jar
-....
+----
[[writing-helloworld-example]]
==== Writing a HelloWorld Example
@@ -56,7 +54,7 @@ The link:#embedding[Embedding Jetty] section contains many examples of writing a
This tutorial uses a simple HelloWorld handler with a main method to run the server.
You can either link:{GITBROWSEURL}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/HelloWorld.java[download] or create in an editor the file `HelloWorld.java` with the following content:
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/HelloWorld.java[]
----
@@ -66,21 +64,21 @@ include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/Hel
The following command compiles the HelloWorld class:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> mkdir classes
> javac -d classes -cp jetty-all-uber.jar HelloWorld.java
-....
+----
[[running-handler-and-server]]
==== Running the Handler and Server
The following command runs the HelloWorld example:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> java -cp classes:jetty-all-uber.jar org.eclipse.jetty.embedded.HelloWorld
-....
+----
You can now point your browser at http://localhost:8080/[http://localhost:8080] to see your hello world page.
diff --git a/jetty-documentation/src/main/asciidoc/development/frameworks/cdi.adoc b/jetty-documentation/src/main/asciidoc/development/frameworks/cdi.adoc
index a47bac65216b..71ca0df6e18b 100644
--- a/jetty-documentation/src/main/asciidoc/development/frameworks/cdi.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/frameworks/cdi.adoc
@@ -98,13 +98,11 @@ This module is equivalent to directly modifying the class path configuration wit
-------------------------------------------------------------
-____
[TIP]
+====
The `cdi2` module or directly modifying the web application classpath will not work for Jetty 10.0.0 and later.
It should only be used for versions prior to Jetty 9.4.20 and/or Weld 3.1.2.Final
-____
-
-
+====
[[cdi-embedded]]
==== Embedded Jetty with CDI
When starting embedded Jetty programmatically from the `main` method, to use CDI it may be
diff --git a/jetty-documentation/src/main/asciidoc/development/frameworks/metro.adoc b/jetty-documentation/src/main/asciidoc/development/frameworks/metro.adoc
index 9dc336e3a939..9bdb7d0f6bcc 100644
--- a/jetty-documentation/src/main/asciidoc/development/frameworks/metro.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/frameworks/metro.adoc
@@ -31,7 +31,7 @@ We'll refer to the unpacked location as `$metro.home`.
3. Copy the jars from $metro.home/lib to `$jetty.home/lib/metro`
4. Edit the start.ini file and add an OPTION line for metro near the end.
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
OPTIONS=metro
----
@@ -43,8 +43,8 @@ The Metro distribution you downloaded should also contain several example web ap
Here's an example of the log output from Jetty when one of the sample Metro wars (from `$metro.home/samples/async`) is deployed to Jetty:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[2093] java -jar start.jar
2013-07-26 15:47:53.480:INFO:oejs.Server:main: jetty-9.0.4.v20130625
@@ -59,4 +59,4 @@ INFO: WSSERVLET14: JAX-WS servlet initializing
2013-07-26 15:47:56.853:INFO:oejs.ServerConnector:main: Started ServerConnector@47dce809{HTTP/1.1}{0.0.0.0:8080}
-....
+----
diff --git a/jetty-documentation/src/main/asciidoc/development/frameworks/osgi.adoc b/jetty-documentation/src/main/asciidoc/development/frameworks/osgi.adoc
index e7059fdef4e4..ed38b3c3d025 100644
--- a/jetty-documentation/src/main/asciidoc/development/frameworks/osgi.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/frameworks/osgi.adoc
@@ -59,11 +59,10 @@ You *must also install the Apache Aries SPI Fly bundles* as many parts of Jetty
|https://repo1.maven.org/maven2/org/apache/aries/spifly/org.apache.aries.spifly.dynamic.bundle/[Maven central]
|=======================================================================
-____
[NOTE]
+====
We strongly recommend that you also deploy the link:#osgi-annotations[annotation-related] jars also, as the Servlet Specification increasingly relies on annotations for functionality.
-____
-
+====
You will also need the **OSGi Event Management service** and the **OSGi Configuration Management service**.
If your OSGi container does not automatically make these available, you will need to add them in a way appropriate to your container.
@@ -93,7 +92,7 @@ Either this property _or_ the *jetty.home.bundle* _must_ be specified.
This property should point to a file system location that has an `etc/` directory containing xml files to configure the Jetty container on startup.
For example:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
jetty.home=/opt/custom/jetty
@@ -102,7 +101,7 @@ jetty.home=/opt/custom/jetty
+
Where `/opt/custom/jetty` contains:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
etc/jetty.xml
@@ -118,7 +117,7 @@ The `jettyhome/` directory should have a subdirectory called `etc/` that contain
The jetty-osgi-boot.jar contains a `jettyhome/` directory with a default set of xml configuration files.
Here's how you would specify it:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
jetty.home.bundle=org.eclipse.jetty.osgi.boot
----
@@ -126,7 +125,7 @@ jetty.home.bundle=org.eclipse.jetty.osgi.boot
+
Here's a partial listing of that jar that shows you the names of the xml files contained within it:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
META-INF/MANIFEST.MF
jettyhome/etc/jetty.xml
@@ -138,7 +137,7 @@ jetty.etc.config.urls::
This specifies the paths of the xml files that are to be used.
If not specified, they default to:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
etc/jetty.xml,etc/jetty-http.xml,etc/jetty-deploy.xml
----
@@ -149,9 +148,9 @@ If the path is relative, it is resolved against either *jetty.home* or **jetty.h
You can use this ability to mix and match jetty configuration files to add functionality, such as adding in a https connector.
Here's an example of adding a HTTPS connector, using the relevant files from the jetty-distribution:
+
-....
+----
etc/jetty.xml, etc/jetty-http.xml, /opt/jetty/etc/jetty-ssl.xml, /opt/jetty/etc/jetty-https.xml, etc/jetty-deploy.xml
-....
+----
+
Note that regardless of whether you set the *jetty.home* or *jetty.home.bundle* property, when Jetty executes the configuration files, it will set an appropriate value for *jetty.home* so that references in xml files to `` will work.
@@ -163,7 +162,7 @@ You can now go ahead and deploy the jetty-osgi-boot.jar into your OSGi container
A Jetty server instance will be created, the xml config files applied to it, and then published as an OSGi service.
Normally, you will not need to interact with this service instance, however you can retrieve a reference to it using the usual OSGi API:
-[source, java, subs="{sub-order}"]
+[source, java]
----
org.osgi.framework.BundleContext bc;
org.osgi.framework.ServiceReference ref = bc.getServiceReference("org.eclipse.jetty.server.Server");
@@ -187,7 +186,7 @@ the Server's name.
Here's an example of how to create a new Server instance and register it with OSGi so that the jetty-osgi-boot code will find it and configure it so it can be a deployment target:
-[source, java, subs="{sub-order}"]
+[source, java]
----
public class Activator implements BundleActivator
{
@@ -213,7 +212,7 @@ public class Activator implements BundleActivator
Now that we have created a new Server called "fooServer", we can deploy webapps and `ContextHandlers` as Bundles or Services to it (see below for more information on this). Here's an example of deploying a webapp as a Service and targeting it to the "fooServer" Server we created above:
-[source, java, subs="{sub-order}"]
+[source, java]
----
public class Activator implements BundleActivator
{
@@ -248,7 +247,7 @@ Here's an example of a bundle where the resources of the webapp are not located
+
`MANIFEST`:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
Bundle-Name: Web
Jetty-WarResourcePath: web
@@ -260,7 +259,7 @@ Bundle-SymbolicName: com.acme.sample.web
+
Bundle contents:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
META-INF/MANIFEST.MF
web/index.html
@@ -277,7 +276,7 @@ Here's an example based on the previous one where we use the `Web-ContextPath` h
+
`MANIFEST`:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
Bundle-Name: Web
Jetty-WarResourcePath: web
@@ -324,14 +323,14 @@ If the `MANIFEST` does not contain that header, then Jetty will concoct a contex
For example, suppose we have a bundle whose location is:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
file://some/where/over/the/rainbow/oz.war
----
The corresponding synthesized context path would be:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
/oz
----
@@ -343,7 +342,7 @@ This xml file must be placed in `META-INF` of the bundle, and must be called `je
Here's an example of a webapp bundle listing containing such a file:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
META-INF/MANIFEST.MF
META-INF/jetty-webapp-context.xml
@@ -356,7 +355,7 @@ com/acme/sample/web/MyOtherStuff.class
Here's an example of the contents of a `META-INF/jetty-webapp-context.xml` file:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -388,28 +387,28 @@ The context files can be inside the bundle, external to the bundle somewhere on
+
A context file that is inside the bundle:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
Jetty-ContextFilePath: ./a/b/c/d/foo.xml
----
+
A context file that is on the file system:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
Jetty-ContextFilePath: /opt/app/contexts/foo.xml
----
+
A context file that is relative to jetty.home:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
Jetty-ContextFilePath: contexts/foo.xml
----
+
A number of different context files:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
Jetty-ContextFilePath: ./a/b/c/d/foo.xml,/opt/app/contexts/foo.xml,contexts/foo.xml
----
@@ -437,7 +436,7 @@ Note that this could be either a directory in the file system if the OSGi contai
Here's an example of a context xml file that makes use of these properties:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/jetty-osgi/test-jetty-osgi-context/src/main/context/acme.xml[]
----
@@ -452,7 +451,7 @@ Here's an example of doing that with a simple bundle that serves static content,
The bundle contents:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
META-INF/MANIFEST.MF
index.html
@@ -461,7 +460,7 @@ com/acme/osgi/Activator.class
The `MANIFEST.MF`:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
Bundle-Classpath: .
Bundle-Name: Jetty OSGi Test WebApp
@@ -481,7 +480,7 @@ Bundle-SymbolicName: com.acme.testwebapp
The Activator code:
-[source, java, subs="{sub-order}"]
+[source, java]
----
public void start(BundleContext context) throws Exception
{
@@ -532,7 +531,7 @@ Here's an example of doing that with a simple bundle that serves static content
The bundle contents:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
META-INF/MANIFEST.MF
static/index.html
@@ -543,7 +542,7 @@ com/acme/osgi/Activator$1.class
The `MANIFEST`:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
Bundle-Classpath: .
Bundle-Name: Jetty OSGi Test Context
@@ -564,7 +563,7 @@ Bundle-SymbolicName: com.acme.testcontext
The Activator code:
-[source, java, subs="{sub-order}"]
+[source, java]
----
public void start(final BundleContext context) throws Exception
{
@@ -593,7 +592,7 @@ public void start(final BundleContext context) throws Exception
The contents of the `acme.xml` context file:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/jetty-osgi/test-jetty-osgi-context/src/main/context/acme.xml[]
----
@@ -688,15 +687,14 @@ Here is the list of recommended jars (NOTE the version numbers may change in fut
|https://repo1.maven.org/maven2/org/eclipse/jetty/osgi/jetty-osgi-boot-jsp[Maven central]
|=======================================================================
-____
[NOTE]
+====
1. As of Jetty 9.2.3 the jetty-osgi-boot-jsp bundle changed to using Apache Jasper as the JSP implementation.
Prior to this the Glassfish Jasper implementation was used, which had a different set of dependencies - pay careful attention to the jars listed both at the top of this page and in this section, as deployment of other jars can cause incomplete or incorrect package resolution in the OSGi container.
2. The order of deployment is important.
Deploy these bundles in the order shown or you may experience strange failures in the compilation of jsps.
This can be hard to diagnose but is almost always caused by the `ServletContainerInitializer` in the `org.eclipse.jetty.apache-jsp` bundle for the jsp container not being invoked due to incorrect startup of the annotation jars.
-____
-
+====
For the JSTL library, we recommend the use of the implementation from Glassfish, as it has fewer dependencies:
.Jars Required for Glassfish JSTL
@@ -751,7 +749,7 @@ This is necessary because the classloading regime used by the OSGi container is
Firstly, lets look at an example of a web bundle's modified `MANIFEST` file so you get an idea of what is required.
This example is a web bundle that uses the Spring servlet framework:
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
Bundle-SymbolicName: com.acme.sample
Bundle-Name: WebSample
@@ -782,7 +780,7 @@ org.eclipse.jetty.osgi.tldbundles::
System property defined on the OSGi environment that is a comma separated list of symbolic names of bundles containing taglibs that will be treated as if they are on the container's classpath for web bundles.
For example:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
org.eclipse.jetty.osgi.tldbundles=com.acme.special.tags,com.foo.web,org.bar.web.framework
----
@@ -798,7 +796,7 @@ In that case, it can be specified on the `org.eclipse.jetty.deploy.DeploymentMan
The `jetty-osgi-boot.jar` contains the default `jettyhome/etc/jetty-deploy.xml` file where the `DeploymentManager` is defined.
To set the pattern, you will need to provide your own etc files - see the section on link:#customize-jetty-container[customizing the jetty container] for how to do this. Here's how the `jetty-deploy.xml` file would look if we defined a pattern that matched all bundle symbolic names ending in "tag" and "web":
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -860,16 +858,14 @@ org.eclipse.jetty.orbit:javax.mail.glassfish-1.4.1.v201005082020.jar)^*^
|jetty-annotations |org.eclipse.jetty.annotations |Distribution lib/
|=======================================================================
-____
[IMPORTANT]
+====
If you wish to use JSPs you will need to deploy these annotation-related jars.
-____
-
-____
+====
[NOTE]
+====
You may be able to deploy later versions or other providers of these specifications, however these particular versions are known to have correct manifests and have been tested and known to work with OSGi.
-____
-
+====
Even if your webapp itself does not not use annotations, you may need to deploy these jars because your webapp depends on a Jetty module or a 3rd party library that uses a http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html[javax.servlet.ServletContainerInitializer].
This interface requires annotation support.
It is implemented by providers of code that extend the capabilities of the container.
@@ -1093,7 +1089,7 @@ org.osgi.framework.system.packages=org.osgi.framework;version=1.7.0, org.osgi.fr
You should now be able to start Felix, and deploy all the jars listed on this page.
You should see output similar to this on the console, using the `felix:lb` command:
-....
+----
ID|State |Level|Name
0|Active | 0|System Bundle (4.4.1)
1|Active | 1|ASM (7.0)
@@ -1132,7 +1128,7 @@ You should see output similar to this on the console, using the `felix:lb` comma
35|Active | 1|Eclipse Compiler for Java(TM) (3.8.2.v20130121-145325)
36|Active | 1|Mortbay EL API and Implementation (8.5.33.1)
37|Active | 1|Mortbay Jasper (8.5.33.1)
-....
+----
===== Eclipse
diff --git a/jetty-documentation/src/main/asciidoc/development/frameworks/spring-usage.adoc b/jetty-documentation/src/main/asciidoc/development/frameworks/spring-usage.adoc
index afeff5fca2af..890eed06ff0d 100644
--- a/jetty-documentation/src/main/asciidoc/development/frameworks/spring-usage.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/frameworks/spring-usage.adoc
@@ -28,10 +28,10 @@ If you want to replace the jetty-xml being used to start the normal Jetty distri
The skeleton of a jetty spring module can be enabled from the jetty-distribution via the link:#startup-modules[module mechanism].
For example:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ java -jar start.jar --add-to-start=spring
-....
+----
This (or the alternative link:#start-jar[--add-to-start]=spring command) creates a `${jetty.home}/lib/spring` directory and populates it with the jetty-spring integration jar.
It does NOT supply the spring jars and their dependencies.
@@ -42,7 +42,7 @@ You will need to download these and place them into jetty's classpath - you can
Configuring Jetty via Spring is simply a matter of calling the API as Spring beans.
The following is an example mimicking the default jetty startup configuration.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
diff --git a/jetty-documentation/src/main/asciidoc/development/frameworks/weld.adoc b/jetty-documentation/src/main/asciidoc/development/frameworks/weld.adoc
index 19c68531adab..670844f714df 100644
--- a/jetty-documentation/src/main/asciidoc/development/frameworks/weld.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/frameworks/weld.adoc
@@ -30,22 +30,22 @@ This can be accomplished either by enabling one of the startup link:#startup-mod
* the `cdi-decorate` module is the preferred Weld integration.
The activation of this module by Weld can be confirmed by the following Weld log:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
INFO: WELD-ENV-001212: Jetty CdiDecoratingListener support detected, CDI injection will be available in Listeners, Servlets and Filters.
-....
+----
* the `cdi-spi` module works with Weld, but may restrict some non standard features.
The activation of this module by Weld can be confirmed by the following Weld log:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
INFO: WELD-ENV-001213: Jetty CDI SPI support detected, CDI injection will be available in Listeners, Servlets and Filters.
-....
+----
* the deprecated `cdi2` module works with Weld prior to 3.1.2.Final.
The activation of this module by Weld can be confirmed by the following Weld log:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
INFO: WELD-ENV-001201: Jetty 7.2+ detected, CDI injection will be available in Servlets and Filters. Injection into Listeners is not supported.
-....
+----
To activate the preferred `cdi-decorate` module use:
-------------------------
@@ -53,11 +53,10 @@ cd $JETTY_BASE
java -jar $JETTY_HOME/start.jar --add-to-start=cdi-decorate
-------------------------
-____
[TIP]
+====
For use with the jetty-maven-plugin, the best idea is to make the org.jboss.weld.servlet:weld-servlet and jetty-cdi artifacts _plugin_ dependencies (__not__ a webapp dependency).
-____
-
+====
[[weld-embedded]]
==== Weld with Embedded Jetty
diff --git a/jetty-documentation/src/main/asciidoc/development/handlers/writing-custom-handlers.adoc b/jetty-documentation/src/main/asciidoc/development/handlers/writing-custom-handlers.adoc
index 02c8a31b0ffe..9db86b46fbdd 100644
--- a/jetty-documentation/src/main/asciidoc/development/handlers/writing-custom-handlers.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/handlers/writing-custom-handlers.adoc
@@ -36,7 +36,7 @@ Classes that implement this interface are used to coordinate requests, filter re
The core API of the Handler interface is:
-[source, java, subs="{sub-order}"]
+[source, java]
----
public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response)
throws IOException, ServletException
@@ -69,7 +69,7 @@ More often than not, access to the Jetty implementations of these classes is req
However, as the request and response may be wrapped by handlers, filters and servlets, it is not possible to pass the implementation directly.
The following mantra retrieves the core implementation objects from under any wrappers:
-[source, java, subs="{sub-order}"]
+[source, java]
----
Request base_request = request instanceof Request ? (Request)request : HttpConnection.getCurrentConnection().getHttpChannel().getRequest();
Response base_response = response instanceof Response ? (Response)response : HttpConnection.getCurrentConnection().getHttpChannel().getResponse();
@@ -107,7 +107,7 @@ The link:{JDURL}/org/eclipse/jetty/embedded/OneHandler.html[`OneHandler`] embedd
You can use the standard servlet response API, which will typically set some status, content headers and then write out the content:
-[source, java, subs="{sub-order}"]
+[source, java]
----
response.setContentType("text/html");
response.setStatus(HttpServletResponse.SC_OK);
@@ -116,7 +116,7 @@ You can use the standard servlet response API, which will typically set some sta
It is also very important that a handler indicate that it has completed handling the request and that the request should not be passed to other handlers:
-[source, java, subs="{sub-order}"]
+[source, java]
----
Request base_request = (request instanceof Request) ? (Request)request:HttpConnection.getCurrentConnection().getHttpChannel().getRequest();
base_request.setHandled(true);
@@ -141,7 +141,7 @@ You can also update the context of the request:
Typically Jetty passes a modified request to another handler and undoes modifications in a finally block afterwards:
-[source, java, subs="{sub-order}"]
+[source, java]
----
try
{
diff --git a/jetty-documentation/src/main/asciidoc/development/maven/jetty-jspc-maven-plugin.adoc b/jetty-documentation/src/main/asciidoc/development/maven/jetty-jspc-maven-plugin.adoc
index aba506f54b29..11099192bbde 100644
--- a/jetty-documentation/src/main/asciidoc/development/maven/jetty-jspc-maven-plugin.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/maven/jetty-jspc-maven-plugin.adoc
@@ -26,7 +26,7 @@ This plugin will help you pre-compile your jsps and works in conjunction with th
Here's the basic setup required to put the jspc plugin into your build:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -117,7 +117,7 @@ You can download the javadoc https://repo1.maven.org/maven2/org/glassfish/web/ja
Taking all the default settings, here's how to configure the war plugin to use the generated `web.xml` that includes all of the jsp servlet declarations:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.apache.maven.plugins
@@ -135,7 +135,7 @@ As compiling jsps is usually done during preparation for a production release an
For example, the following profile will only be invoked if the flag `-Dprod` is present on the run line:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -164,10 +164,10 @@ For example, the following profile will only be invoked if the flag `-Dprod` is
The following invocation would cause your code to be compiled, the jsps to be compiled, the and s inserted in the `web.xml` and your webapp assembled into a war:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ mvn -Dprod package
-....
+----
[[jspc-overlay-precompile]]
==== Precompiling Jsps with Overlaid Wars
@@ -181,7 +181,7 @@ We will unpack the overlaid war file, compile the jsps and merge their servlet d
Here's an example configuration of the war plugin that separate those phases into an unpack phase, and then a packing phase:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
maven-war-plugin
@@ -218,7 +218,7 @@ Now you also need to configure the `jetty-jspc-maven-plugin` so that it can use
This is in `target/foo/WEB-INF/web.xml`.
Using the default settings, the `web.xml` merged with the jsp servlet definitions will be put into `target/web.xml`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
diff --git a/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-helloworld.adoc b/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-helloworld.adoc
index 2e9448889d38..b06d69fe48f8 100644
--- a/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-helloworld.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-helloworld.adoc
@@ -25,13 +25,12 @@ Based on the concept of a project object model (POM), Maven can manage a project
It is an ideal tool to build a web application project, and such projects can use the link:#jetty-maven-plugin[jetty-maven-plugin] to easily run the web application and save time in development.
You can also use Maven to build, test and run a project which embeds Jetty.
-____
[NOTE]
+====
Use of Maven and the jetty-maven-plugin is *not* required.
Using Maven for Jetty implementations is a popular choice, but users encouraged to manage their projects in whatever way suits their needs.
Other popular tools include Ant and Gradle.
-____
-
+====
First we'll have a look at a very simple HelloWorld java application that embeds Jetty, then a simple webapp which makes use of the link:#jetty-maven-plugin[jetty-maven-plugin] to speed up the development cycle.
[[configuring-embedded-jetty-with-maven]]
@@ -45,19 +44,19 @@ To understand the basic operations of building and running against Jetty, first
Maven uses convention over configuration, so it is best to use the project structure Maven recommends.
You can use _link:#archetypes[http://maven.apache.org/guides/introduction/introduction-to-archetypes.html[archetypes]]_ to quickly setup Maven projects, but we will set up the structure manually for this simple tutorial example:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> mkdir JettyMavenHelloWorld
> cd JettyMavenHelloWorld
> mkdir -p src/main/java/org/example
-....
+----
[[creating-helloworld-class]]
===== Creating the HelloWorld Class
Use an editor to create the file `src/main/java/org/example/HelloWorld.java` with the following contents:
-[source, java, subs="{sub-order}"]
+[source, java]
----
package org.example;
@@ -100,7 +99,7 @@ public class HelloWorld extends AbstractHandler
The `pom.xml` file declares the project name and its dependencies.
Use an editor to create the file `pom.xml` in the `JettyMavenHelloWorld` directory with the following contents:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
mvn clean compile exec:java
-....
+----
You can point your browser to `http://localhost:8080` to see the _Hello World_ page.
You can observe what Maven is doing for you behind the scenes by using the `mvn dependency:tree` command, which reveals the transitive dependency resolved and downloaded as:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> mvn dependency:tree
[INFO] Scanning for projects...
...
@@ -184,7 +183,7 @@ You can observe what Maven is doing for you behind the scenes by using the `mvn
[INFO] Finished at: 2016-08-01T13:46:42-04:00
[INFO] Final Memory: 15M/209M
[INFO] ------------------------------------------------------------------------
-....
+----
[[developing-standard-webapp-with-jetty-and-maven]]
==== Developing a Standard WebApp with Jetty and Maven
@@ -193,20 +192,20 @@ The previous section demonstrated how to use Maven with an application that embe
Now we will examine instead how to develop a standard webapp with Maven and Jetty.
First create the Maven structure (you can use the maven webapp archetype instead if you prefer):
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> mkdir JettyMavenHelloWarApp
> cd JettyMavenHelloWebApp
> mkdir -p src/main/java/org/example
> mkdir -p src/main/webapp/WEB-INF
-....
+----
[[creating-servlet]]
===== Creating a Servlet
Use an editor to create the file `src/main/java/org/example/HelloServlet.java` with the following contents:
-[source, java, subs="{sub-order}"]
+[source, java]
----
package org.example;
@@ -230,7 +229,7 @@ public class HelloServlet extends HttpServlet
You need to declare this servlet in the deployment descriptor, so create the file `src/main/webapp/WEB-INF/web.xml` and add the following contents:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
mvn jetty:run
-....
+----
You can see the static and dynamic content at `http://localhost:8080/hello`
@@ -317,9 +316,9 @@ The full reference is at link:#jetty-maven-plugin[Configuring the Jetty Maven Pl
You can create a Web Application Archive (WAR) file from the project with the command:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
> mvn package
-....
+----
The resulting war file is in the `target` directory and may be deployed on any standard servlet server, including link:#configuring-deployment[Jetty].
diff --git a/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-plugin.adoc b/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-plugin.adoc
index f5fe6ef9862d..869cd1708f81 100644
--- a/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-plugin.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/maven/jetty-maven-plugin.adoc
@@ -24,11 +24,10 @@ You can add it to any webapp project that is structured according to the Maven d
The plugin can then periodically scan your project for changes and automatically redeploy the webapp if any are found.
This makes the development cycle more productive by eliminating the build and deploy steps: you use your IDE to make changes to the project, and the running web container automatically picks them up, allowing you to test them straight away.
-____
[IMPORTANT]
+====
You should use Maven 3.3+ for this plugin.
-____
-
+====
While the Jetty Maven Plugin can be very useful for development we do not recommend its use in a production capacity.
In order for the plugin to work it needs to leverage many internal Maven apis and Maven itself it not a production deployment tool.
We recommend either the traditional distribution deployment approach or using link:#advanced-embedding[embedded Jetty.]
@@ -38,7 +37,7 @@ We recommend either the traditional distribution deployment approach or using li
First, add `jetty-maven-plugin` to your `pom.xml` definition:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -49,10 +48,10 @@ First, add `jetty-maven-plugin` to your `pom.xml` definition:
Then, from the same directory as your root `pom.xml`, type:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
mvn jetty:run
-....
+----
This starts Jetty and serves up your project on http://localhost:8080/.
@@ -62,12 +61,11 @@ If you save changes and recompile your class files, Jetty redeploys your webapp,
You can terminate the plugin with a `ctrl-c` in the terminal window where it is running.
-____
[NOTE]
+====
The classpath of the running Jetty instance and its deployed webapp are managed by Maven, and may not be exactly what you expect.
For example: a webapp's dependent jars might be referenced via the local repository, not the `WEB-INF/lib` directory.
-____
-
+====
[[running-and-deploying]]
==== Supported Goals
@@ -79,17 +77,17 @@ There are different goals to accomplish these tasks, as well as several others.
To see a list of all goals supported by the Jetty Maven plugin, do:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
mvn jetty:help
-....
+----
To see the detailed list of parameters that can be configured for a particular goal, in addition to its description, do:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
mvn jetty:help -Ddetail=true -Dgoal=
-....
+----
[[configuring-jetty-container]]
==== Configuring the Jetty Container
@@ -200,7 +198,7 @@ Sets up various characteristics of the link:{GITBROWSEURL}/jetty-server/src/main
Importantly, it sets up the link:{GITBROWSEURL}/jetty-server/src/main/java/org/eclipse/jetty/server/HttpConfiguration.java[`org.eclipse.jetty.server.HttpConfiguration`] element that we can refer to in subsequent xml files that configure the connectors.
Below is the relevant section taken from link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty.xml[jetty.xml].
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
...
@@ -233,21 +231,21 @@ jetty-ssl.xml::
Sets up ssl which will be used by the https connector.
Here's the `jetty-ssl.xml` file from the jetty-distribution:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/jetty-server/src/main/config/etc/jetty-ssl.xml[]
----
jetty-https.xml::
Set up the https connector using the HttpConfiguration from `jetty.xml` and the ssl configuration from `jetty-ssl.xml`:
+
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/jetty-server/src/main/config/etc/jetty-https.xml[]
----
Now you need to let the plugin know to apply the files above:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -259,22 +257,21 @@ Now you need to let the plugin know to apply the files above:
----
-____
[CAUTION]
+====
Just as with an installed distribution of Jetty, the ordering of the xml files is significant.
-____
-
+====
You can also use Jetty xml files to configure a http connector for the plugin to use.
Here we use the same `jetty-http.xml` file from the Jetty distribution:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/jetty-server/src/main/config/etc/jetty-http.xml[]
----
Now we add it to the list of configs for the plugin to apply:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -354,15 +351,14 @@ You do not need to assemble the webapp into a WAR, saving time during the develo
Once invoked, you can configure the plugin to run continuously, scanning for changes in the project and automatically performing a hot redeploy when necessary.
Any changes you make are immediately reflected in the running instance of Jetty, letting you quickly jump from coding to testing, rather than going through the cycle of: code, compile, reassemble, redeploy, test.
-____
[NOTE]
+====
As of Jetty 9.4.7, when using jetty:run in a multi-module build, it is no longer necessary to build each of the modules that form dependencies of the webapp first.
Thus, if your webapp depends on other modules in your project and they are present in the reactor at the same time, jetty will use their compiled classes rather than their jar files from your local maven repository.
-____
-
+====
Here is an example, which turns on scanning for changes every ten seconds, and sets the webapp context path to `/test`:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -418,7 +414,7 @@ Patterns are specified as a relative path using a glob-like syntax as described
Here's an example:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
...
@@ -482,7 +478,7 @@ If this is not sufficient, set it to your custom location.
Here's how to set it:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
...
@@ -515,7 +511,7 @@ This defaults to `${project.build.directory}/${project.build.finalName}`, but yo
Here's how to set it:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
...
@@ -550,7 +546,7 @@ Alternatively, you can set this parameter to false, in which case Jetty will blo
Here's the configuration:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -658,22 +654,21 @@ Use the `jvmArgs` parameter to pass system properties to the forked process.
To deploy your unassembled web app to Jetty running in a new JVM:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
mvn jetty:run-forked
-....
+----
Jetty continues to execute until you either:
* Press `ctrl-c` in the terminal window to stop the plugin, which also stops the forked JVM (only if you started with `waitForChild=true`)
* Use `jetty:stop` to stop the forked JVM, which also stops the plugin.
-____
[NOTE]
+====
If you want to set a custom port for the Jetty connector you need to specify it in a `jetty xml` file rather than setting the connector and port tags.
You can specify the location of the `jetty.xml` using the `jettyXml` parameter.
-____
-
+====
[[jetty-run-distro-goal]]
==== jetty:run-distro
@@ -722,11 +717,10 @@ javaPath::
Default will be your `${java.home}/bin/java`
This the java executable used to start the child process
-____
[NOTE]
+====
Use the `modules` parameter to configure the Jetty distribution appropriately rather than using jetty artifacts as `plugin dependencies`.
-____
-
+====
The following `jetty:run` parameters are *NOT* applicable to this goal:
* *scanTargets*
@@ -757,7 +751,7 @@ Not supported.
Use the `jvmArgs` parameter to pass system properties to the forked process.
Here's an example of using the configuration parameters:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -794,19 +788,17 @@ Here's an example of using the configuration parameters:
----
-____
[NOTE]
+====
When defining modules for this goal, use the standard link:#startup-modules[Jetty module] names and not the name of the related Jetty sub-project.
For example, in the configuration above support for JMX is configured by adding the `jmx` Jetty module and not the `jetty-jmx` sub-project.
-____
-
-
+====
To deploy your unassembled web app to jetty running as a local distribution:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
mvn jetty:run-distro
-....
+----
[[jetty-start-goal]]
@@ -820,7 +812,7 @@ For example, you can configure the plugin to start your webapp at the beginning
To do this, you need to set up a couple of `execution` scenarios for the Jetty plugin.
You use the `pre-integration-test` and `post-integration-test` Maven build phases to trigger the execution and termination of Jetty:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -870,7 +862,7 @@ If false or not specified, the plugin does not wait for confirmation but exits a
Here's a configuration example:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -889,10 +881,10 @@ Here's a configuration example:
Then, while Jetty is running (in another window), type:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
mvn jetty:stop
-....
+----
The `stopPort` must be free on the machine you are running on.
If this is not the case, you will get an "Address already in use" error message after the "Started ServerConnector ..." message.
@@ -917,7 +909,7 @@ The full path name of a file into which you would like the effective web xml gen
You can also generate the origin of each element into the effective web.xml file.
The origin is either a descriptor eg web.xml,web-fragment.xml,override-web.xml file, or an annotation eg @WebServlet.
Some examples of elements with origin attribute information are:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -948,7 +940,7 @@ This is probably best seen by looking at a concrete example.
Suppose your webapp depends on the following wars:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
com.acme
@@ -982,7 +974,7 @@ WebAppY:
They are configured for the http://maven.apache.org/plugins/maven-war-plugin/overlays.html[maven-war-plugin]:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.apache.maven.plugins
@@ -1025,7 +1017,7 @@ The configuration parameter `` (see the section on link:#configuri
For example, suppose our webapp depends on these two wars:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
com.acme
@@ -1076,7 +1068,7 @@ Then our webapp has available these additional resources:
You can configure LoginServices in the plugin.
Here's an example of setting up the HashLoginService for a webapp:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -1107,7 +1099,7 @@ It's a lot like the overlaid war situation, but without the war.
Here is a configuration example:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -1129,7 +1121,7 @@ If you want to deploy webapp A, and webapps B and C in the same Jetty instance:
Putting the configuration in webapp A's `pom.xml`:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -1154,16 +1146,15 @@ Putting the configuration in webapp A's `pom.xml`:
----
-____
[IMPORTANT]
+====
If the `ContextHandler` you are deploying is a webapp, it is *essential* that you use an `org.eclipse.jetty.maven.plugin.JettyWebAppContext` instance rather than a standard `org.eclipse.jetty.webapp.WebAppContext` instance.
Only the former will allow the webapp to function correctly in the maven environment.
-____
-
+====
Alternatively, add a `jetty.xml` file to webapp A.
Copy the `jetty.xml` file from the Jetty distribution, and then add WebAppContexts for the other 2 webapps:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
[
@@ -1187,7 +1178,7 @@ Copy the `jetty.xml` file from the Jetty distribution, and then add WebAppContex
Then configure the location of this `jetty.xml` file into webapp A's jetty plugin:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -1220,7 +1211,7 @@ This feature is useful to tidy up the command line and save a lot of typing.
However, *sometimes it is not possible to use this feature to set System properties* - sometimes the software component using the System property is already initialized by the time that maven runs (in which case you will need to provide the System property on the command line), or by the time that Jetty runs.
In the latter case, you can use the link:http://www.mojohaus.org/[maven properties plugin] to define the system properties instead. Here's an example that configures the logback logging system as the Jetty logger:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.codehaus.mojo
@@ -1244,17 +1235,16 @@ In the latter case, you can use the link:http://www.mojohaus.org/[maven properti
----
-____
[NOTE]
+====
If a System property is already set (for example, from the command line or by the JVM itself), then by default these configured properties *DO NOT* override them (see below for use of the parameter).
-____
-
+====
[[specifying-properties-in-pom]]
===== Specifying System Properties in the POM
Here's an example of how to specify System properties in the POM:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -1276,7 +1266,7 @@ Here's an example of how to specify System properties in the POM:
To change the default behavior so that these system properties override those on the command line, use the `` parameter:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -1311,7 +1301,7 @@ fooprop=222
This can be configured on the plugin like so:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
diff --git a/jetty-documentation/src/main/asciidoc/development/part.adoc b/jetty-documentation/src/main/asciidoc/development/part.adoc
index 83cbc9da51d0..ea70d5e52800 100644
--- a/jetty-documentation/src/main/asciidoc/development/part.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/part.adoc
@@ -18,7 +18,7 @@
[[jetty-dev-guide]]
-= Jetty Development Guide
+== Jetty Development Guide
include::embedding/chapter.adoc[]
include::clients/http/chapter.adoc[]
diff --git a/jetty-documentation/src/main/asciidoc/development/websockets/intro/chapter.adoc b/jetty-documentation/src/main/asciidoc/development/websockets/intro/chapter.adoc
index 695d2ffe414a..149017296a54 100644
--- a/jetty-documentation/src/main/asciidoc/development/websockets/intro/chapter.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/websockets/intro/chapter.adoc
@@ -52,18 +52,16 @@ We support the version 13 of the released and final spec.
+
Jetty tests its WebSocket protocol implementation using the http://autobahn.ws/testsuite[autobahn testsuite].
-____
[IMPORTANT]
+====
The early drafts of WebSocket were supported in Jetty 7 and Jetty 8, but this support has been removed in Jetty 9.
This means that Jetty 9 will not support the old browsers that implemented the early drafts of WebSocket. (such as Safari 5.0 or Opera 12)
-____
-
-____
+====
[TIP]
+====
Want to know if the browser you are targeting supports WebSocket?
Use http://caniuse.com/websockets[caniuse.com/websockets] to find out.
-____
-
+====
http://www.jcp.org/en/jsr/detail?id=356[JSR-356]::
The Java WebSocket API (`javax.websocket`)
+
@@ -116,7 +114,7 @@ Completely disable jsr-356 for a particular webapp:::
Set the `org.eclipse.jetty.containerInitializerExclusionPattern` link:#context_attributes[context attribute] to include `org.eclipse.jetty.websocket.jsr356.server.deploy.WebSocketServerContainerInitializer`.
Here's an example of doing this in code, although you can do the link:#intro-jetty-configuration-webapps[same in xml]:
+
-[source, java, subs="{sub-order}"]
+[source, java]
----
WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerExclusionPattern",
diff --git a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-adapter.adoc b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-adapter.adoc
index 862c45611da0..de8c331f75a7 100644
--- a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-adapter.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-adapter.adoc
@@ -21,7 +21,7 @@
A basic adapter for managing the Session object on the WebSocketListener.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/jetty-websocket/websocket-common/src/test/java/examples/echo/AdapterEchoSocket.java[]
----
diff --git a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-annotations.adoc b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-annotations.adoc
index ba1849835437..60ae5421baef 100644
--- a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-annotations.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-annotations.adoc
@@ -22,7 +22,7 @@
The most basic form of WebSocket is a marked up POJO with annotations
provided by the Jetty WebSocket API.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/jetty-websocket/websocket-common/src/test/java/examples/echo/AnnotatedEchoSocket.java[]
----
diff --git a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-listener.adoc b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-listener.adoc
index c13c11a90d82..bc4a84951705 100644
--- a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-listener.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-listener.adoc
@@ -21,7 +21,7 @@
The basic form of a WebSocket using the link:{JDURL}/org/eclipse/jetty/websocket/api/WebSocketListener.html[`org.eclipse.jetty.websocket.api.WebSocketListener`] for incoming events.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/jetty-websocket/websocket-common/src/test/java/examples/echo/ListenerEchoSocket.java[]
----
diff --git a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-send-message.adoc b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-send-message.adoc
index b4d0f6f58cda..1af7b4001745 100644
--- a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-send-message.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-send-message.adoc
@@ -28,7 +28,7 @@ With RemoteEndpoint you can choose to send TEXT or BINARY WebSocket messages, or
Most calls are blocking in nature, and will not return until the send has completed (or has thrown an exception).
-[source, java, subs="{sub-order}"]
+[source, java]
----
RemoteEndpoint remote = session.getRemote();
@@ -47,7 +47,7 @@ catch (IOException e)
How to send a simple Binary message using the RemoteEndpoint.
This will block until the message is sent, possibly throwing an IOException if unable to send the message.
-[source, java, subs="{sub-order}"]
+[source, java]
----
RemoteEndpoint remote = session.getRemote();
@@ -71,7 +71,7 @@ This will block until the message is sent, possibly throwing an IOException if u
If you have a large message to send, and want to send it in pieces and parts, you can utilize the partial message sending methods of RemoteEndpoint.
Just be sure you finish sending your message (`isLast == true`).
-[source, java, subs="{sub-order}"]
+[source, java]
----
RemoteEndpoint remote = session.getRemote();
@@ -94,7 +94,7 @@ catch (IOException e)
How to send a Binary message in 2 parts, using the partial message support in RemoteEndpoint.
This will block until each part of the message is sent, possibly throwing an IOException if unable to send the partial message.
-[source, java, subs="{sub-order}"]
+[source, java]
----
RemoteEndpoint remote = session.getRemote();
@@ -120,7 +120,7 @@ This will block until each part of the message is sent, possibly throwing an IOE
You can also send Ping and Pong control frames using the RemoteEndpoint.
-[source, java, subs="{sub-order}"]
+[source, java]
----
RemoteEndpoint remote = session.getRemote();
@@ -140,7 +140,7 @@ catch (IOException e)
How to send a Ping control frame, with a payload of `"You There?"` (arriving at Remote Endpoint as a byte array payload).
This will block until the message is sent, possibly throwing an IOException if unable to send the ping frame.
-[source, java, subs="{sub-order}"]
+[source, java]
----
RemoteEndpoint remote = session.getRemote();
@@ -172,7 +172,7 @@ However there are also 2 Async send message methods available:
Both return a `Future` that can be used to test for success and failure of the message send using standard http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Future.html[`java.util.concurrent.Future`] behavior.
-[source, java, subs="{sub-order}"]
+[source, java]
----
RemoteEndpoint remote = session.getRemote();
@@ -184,7 +184,7 @@ remote.sendBytesByFuture(buf);
How to send a simple Binary message using the RemoteEndpoint.
The message will be enqueued for outgoing write, but you will not know if it succeeded or failed.
-[source, java, subs="{sub-order}"]
+[source, java]
----
RemoteEndpoint remote = session.getRemote();
@@ -205,7 +205,7 @@ catch (ExecutionException | InterruptedException e)
How to send a simple Binary message using the RemoteEndpoint, tracking the `Future` to know if the send succeeded or failed.
-[source, java, subs="{sub-order}"]
+[source, java]
----
RemoteEndpoint remote = session.getRemote();
@@ -237,7 +237,7 @@ catch (TimeoutException e)
How to send a simple Binary message using the RemoteEndpoint, tracking the `Future` and waiting only prescribed amount of time for the send to complete, cancelling the message if the timeout occurs.
-[source, java, subs="{sub-order}"]
+[source, java]
----
RemoteEndpoint remote = session.getRemote();
@@ -248,7 +248,7 @@ remote.sendStringByFuture("Hello World");
How to send a simple Text message using the RemoteEndpoint.
The message will be enqueued for outgoing write, but you will not know if it succeeded or failed.
-[source, java, subs="{sub-order}"]
+[source, java]
----
RemoteEndpoint remote = session.getRemote();
@@ -268,7 +268,7 @@ catch (ExecutionException | InterruptedException e)
How to send a simple Binary message using the RemoteEndpoint, tracking the `Future` to know if the send succeeded or failed.
-[source, java, subs="{sub-order}"]
+[source, java]
----
RemoteEndpoint remote = session.getRemote();
diff --git a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-session.adoc b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-session.adoc
index 5f3fd8d889b6..8b9ef7b224e2 100644
--- a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-session.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-api-session.adoc
@@ -23,7 +23,7 @@ The link:{JDURL}/org/eclipse/jetty/websocket/api/Session.html[Session] object ca
The Connection State (is it open or not).
-[source, java, subs="{sub-order}"]
+[source, java]
----
if(session.isOpen()) {
// send message
@@ -32,7 +32,7 @@ if(session.isOpen()) {
Is the Connection Secure.
-[source, java, subs="{sub-order}"]
+[source, java]
----
if(session.isSecure()) {
// connection is using 'wss://'
@@ -41,7 +41,7 @@ if(session.isSecure()) {
What was in the Upgrade Request and Response.
-[source, java, subs="{sub-order}"]
+[source, java]
----
UpgradeRequest req = session.getUpgradeRequest();
String channelName = req.getParameterMap().get("channelName");
@@ -52,14 +52,14 @@ String subprotocol = resp.getAcceptedSubProtocol();
What is the Local and Remote Address.
-[source, java, subs="{sub-order}"]
+[source, java]
----
InetSocketAddress remoteAddr = session.getRemoteAddress();
----
Get and Set the Idle Timeout
-[source, java, subs="{sub-order}"]
+[source, java]
----
session.setIdleTimeout(2000); // 2 second timeout
----
diff --git a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-client-api.adoc b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-client-api.adoc
index 8f3136cdcd9b..df6102f7fa5c 100644
--- a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-client-api.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-client-api.adoc
@@ -23,7 +23,7 @@ Jetty also provides a Jetty WebSocket Client Library to write make talking to We
To use the Jetty WebSocket Client on your own Java project you will need the following maven artifacts.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty.websocket
@@ -36,14 +36,14 @@ To use the Jetty WebSocket Client on your own Java project you will need the fol
To use the WebSocketClient you will need to hook up a WebSocket object instance to a specific destination WebSocket URI.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/jetty-websocket/websocket-client/src/test/java/examples/SimpleEchoClient.java[]
----
The above example connects to a remote WebSocket server and hands off a SimpleEchoSocket to perform the logic on the websocket once connected, waiting for the socket to register that it has closed.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/jetty-websocket/websocket-client/src/test/java/examples/SimpleEchoSocket.java[]
----
diff --git a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-server-api.adoc b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-server-api.adoc
index 7ce2af928ce6..0f9666699e94 100644
--- a/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-server-api.adoc
+++ b/jetty-documentation/src/main/asciidoc/development/websockets/jetty/jetty-websocket-server-api.adoc
@@ -29,7 +29,7 @@ This will only work when running within the Jetty Container (unlike past Jetty t
To wire up your WebSocket to a specific path via the WebSocketServlet, you will need to extend org.eclipse.jetty.websocket.servlet.WebSocketServlet and specify what WebSocket object should be created with incoming Upgrade requests.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/jetty-websocket/websocket-servlet/src/test/java/examples/MyEchoServlet.java[]
----
@@ -39,13 +39,12 @@ This example will create a Servlet mapped via the http://docs.oracle.com/javaee/
The link:{JDURL}/org/eclipse/jetty/websocket/servlet/WebSocketServlet.html#configure(org.eclipse.jetty.websocket.servlet.WebSocketServletFactory)[`WebSocketServlet.configure(WebSocketServletFactory factory)`] is where you put your specific configuration for your WebSocket.
In the example we specify a 10 second idle timeout and register MyEchoSocket with the default WebSocketCreator the WebSocket class we want to be created on Upgrade.
-____
[NOTE]
+====
It is important that you take in account any firewall or router timeouts
when configuring websockets. Be sure the websocket configuration is
lower than your firewall or router.
-____
-
+====
==== Using the WebSocketCreator
All WebSocket's are created via whatever link:{JDURL}/org/eclipse/jetty/websocket/servlet/WebSocketCreator.html[WebSocketCreator] you have registered with the link:{JDURL}/org/eclipse/jetty/websocket/servlet/WebSocketServletFactory.html[WebSocketServletFactory].
@@ -55,7 +54,7 @@ Use link:{JDURL}/org/eclipse/jetty/websocket/servlet/WebSocketServletFactory.htm
If you have a more complicated creation scenario, you might want to provide your own WebSocketCreator that bases the WebSocket it creates off of information present in the UpgradeRequest object.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/jetty-websocket/websocket-servlet/src/test/java/examples/MyAdvancedEchoCreator.java[]
----
@@ -63,7 +62,7 @@ include::{SRCDIR}/jetty-websocket/websocket-servlet/src/test/java/examples/MyAdv
Here we show a WebSocketCreator that will utilize the http://tools.ietf.org/html/rfc6455#section-1.9[WebSocket subprotocol] information from request to determine what WebSocket type should be
created.
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/jetty-websocket/websocket-servlet/src/test/java/examples/MyAdvancedEchoServlet.java[]
----
diff --git a/jetty-documentation/src/main/asciidoc/index.adoc b/jetty-documentation/src/main/asciidoc/index.adoc
index 7798a489a364..82d77ad8f4a1 100644
--- a/jetty-documentation/src/main/asciidoc/index.adoc
+++ b/jetty-documentation/src/main/asciidoc/index.adoc
@@ -16,8 +16,8 @@
// ========================================================================
//
-Jetty : The Definitive Reference
-================================
+= Jetty : The Definitive Reference
+
:docinfo:
:revnumber: {VERSION}
diff --git a/jetty-documentation/src/main/asciidoc/quick-start/configuring/how-to-configure.adoc b/jetty-documentation/src/main/asciidoc/quick-start/configuring/how-to-configure.adoc
index 567a3c1a6603..8b372d6e90c0 100644
--- a/jetty-documentation/src/main/asciidoc/quick-start/configuring/how-to-configure.adoc
+++ b/jetty-documentation/src/main/asciidoc/quick-start/configuring/how-to-configure.adoc
@@ -52,13 +52,12 @@ The Jetty distribution uses the following configuration files to instantiate, in
* Other start.jar options (see `java -jar start.jar --help`)
* Some JVM options in combination with `--exec`, such as `-Xbootclasspath`.
-____
[NOTE]
+====
--
It is the `ini` files located in the Jetty base directory (if different from Jetty home) that are typically edited to change the configuration (e.g. change ports).
--
-____
-
+====
`mod` files::
The `$JETTY_HOME/modules/*.mod` files contain the definition of modules that can be activated by `--module=name`.
Each `mod` file defines:
@@ -82,7 +81,7 @@ XML files::
Below is an illustration of how the various Jetty configuration files (`ini`, `mod` and XML) are related:
-image:images/Jetty_Configuration_File_Relationships.png[image,width=693]
+image:quick-start/configuring/images/Jetty_Configuration_File_Relationships.png[image,width=693]
==== A Closer Look
@@ -105,7 +104,7 @@ We will work backwards from an ini file to the associated module and then the XM
First up, the `http.ini` file.
If we take a look at it's contents, we will see the following:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ cat start.d/http.ini
# ---------------------------------------
@@ -156,7 +155,7 @@ When a module is enabled and an `ini` file is created, all of the properties you
If you wanted to change one of the properties though, say `jetty.http.port`, you'd simply uncomment the line and change the value.
For example:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ cat start.d/http.ini
# ---------------------------------------
@@ -181,7 +180,7 @@ As seen before, these properties were populated in this ini file based on a rela
Standard Jetty modules live in the Home of the Jetty Distribution in the aptly named `modules` directory.
So let's take a quick look at the associated `$JETTY_HOME/modules/http.mod` file:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ cat $JETTY_HOME/modules/http.mod
[description]
@@ -221,7 +220,7 @@ It is important to note that not every module file will have the same sections,
Now that we know what XML file these properties relate to, we can navigate to it and have a look.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
$ cat $JETTY_HOME/etc/jetty-http.xml
@@ -279,13 +278,12 @@ $ cat $JETTY_HOME/etc/jetty-http.xml
Now we can see where those properties in our `ini` and module files came from.
In Jetty XML files, Jetty objects come to life; defined properties are set which link back to the jar libraries and run the server to a user's specification.
-____
[IMPORTANT]
+====
It is important to remember that you should *not* modify the XML files in your `$JETTY_HOME`.
If you do for some reason feel you want to change the way an XML file operates, it is best to make a copy of it in your `$JETTY_BASE` in an `/etc` directory.
Jetty will always look first to the `$JETTY_BASE` for configuration.
-____
-
+====
==== Other Configuration Files
In addition to the configuration files described above, the configuration of the server can use the following file types:
@@ -316,14 +314,14 @@ Property Files::
To understand the link:#jetty-xml-syntax[Jetty IoC XML format], consider the following example of an embedded Jetty server instantiated and configured in Java:
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ExampleServer.java[]
----
link:#jetty-xml-syntax[Jetty IoC XML format] allows you to instantiate and configure the exact same server in XML without writing any java code:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/examples/embedded/src/main/resources/exampleserver.xml[]
----
diff --git a/jetty-documentation/src/main/asciidoc/quick-start/configuring/what-to-configure.adoc b/jetty-documentation/src/main/asciidoc/quick-start/configuring/what-to-configure.adoc
index 9704f4b9fd23..bf5daf14a788 100644
--- a/jetty-documentation/src/main/asciidoc/quick-start/configuring/what-to-configure.adoc
+++ b/jetty-documentation/src/main/asciidoc/quick-start/configuring/what-to-configure.adoc
@@ -75,30 +75,27 @@ SSL Context Factory::
The TLS connector types (HTTPS and HTTP2) configure an SSL Context Factory with the location of the server keystore and truststore for obtaining server certificates.
-____
[NOTE]
+====
Virtual hosts are not configured on connectors. You must configure individual contexts with the virtual hosts to which they respond.
-____
-
-____
+====
[NOTE]
+====
Prior to Jetty 9, the type of the connector reflected both the protocol supported (HTTP, HTTPS, AJP, SPDY), and the nature of the implementation (NIO or BIO).
From Jetty 9 onwards there is only one prime Connector type (`ServerConnector`), which is NIO based and uses Connection Factories to handle one or more protocols.
-____
-
+====
[[intro-jetty-configuration-contexts]]
==== Configuring Contexts
A Jetty context is a handler that groups other handlers under a context path together with associated resources and is roughly equivalent to the standard ServletContext API.
A context may contain either standard Jetty handlers or a custom application handler.
-____
[NOTE]
+====
The servlet specification defines a web application.
In Jetty a standard web application is a specialized context that uses a standard layout and `WEB-INF/web.xml` to instantiate and configure classpath, resource base and handlers for sessions, security, and servlets, plus servlets for JSPs and static content.
Standard web applications often need little or no additional configuration, but you can also use the techniques for arbitrary contexts to refine or modify the configuration of standard web applications.
-____
-
+====
Configuration values that are common to all contexts are:
contextPath::
@@ -132,7 +129,7 @@ resourceBase::
In an embedded server, you configure contexts by directly calling the link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler] API as in the following example:
-[source, java, subs="{sub-order}"]
+[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneContext.java[]
----
@@ -142,7 +139,7 @@ include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/One
You can create and configure a context entirely by IoC XML (either Jetty's or Spring).
The deployer discovers and hot deploys context IoC descriptors like the following which creates a context to serve the Javadoc from the Jetty distribution:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -283,7 +279,7 @@ In Jetty, there are several realm implementations (called LoginServices) and the
To configure an instance of HashLoginService that matches the "Test Realm" configured above, the following `$JETTY_BASE/etc/test-realm.xml` IoC XML file should be passed on the command line or set in `start.ini` or `start.d/server.ini`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
include::{SRCDIR}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/etc/test-realm.xml[]
----
diff --git a/jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-common-configuration.adoc b/jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-common-configuration.adoc
index 55f6711a4aad..909367475247 100644
--- a/jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-common-configuration.adoc
+++ b/jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-common-configuration.adoc
@@ -32,15 +32,14 @@ jetty.home::
jetty.base::
The property that defines the location of a specific implementation of a Jetty server, its configuration, logs and web applications (typically start.d/*.ini files, logs and webapps).
-____
[IMPORTANT]
+====
Your Jetty Home directory should be treated as a standard of truth and remain unmodified or changed.
Changes or additions to your configuration should take place in the Jetty Base directory.
-____
-
+====
The `jetty.home` and `jetty.base` properties may be explicitly set on the command line, or they can be inferred from the environment if used with commands like:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
> cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar
@@ -48,7 +47,7 @@ The `jetty.home` and `jetty.base` properties may be explicitly set on the comman
The following commands create a new base directory, enables both the HTTP connector and the web application deployer modules, and copies a demo webapp to be deployed:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
> JETTY_BASE=/tmp/mybase
> mkdir $JETTY_BASE
@@ -91,7 +90,7 @@ INFO: Base directory was modified
You can configure Jetty to run on a different port by setting the `jetty.http.port` property on the command line:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
> cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar jetty.http.port=8081
@@ -102,8 +101,8 @@ When the server starts, it will now run on port `8081`.
It is important to note that setting properties on the command line will only take affect for that instance of the server.
To change the configuration so that the server will always start on the desired port, you will need to edit the `start.d/http.ini`
-____
[NOTE]
+====
--
The configuration by properties works via the following chain:
@@ -113,15 +112,14 @@ The configuration by properties works via the following chain:
For more information see the link:#quick-start-configure[Quickstart Configuration Guide] and link:#configuring-connectors[Configuring Connectors].
--
-____
-
+====
[[quickstart-starting-https]]
==== Adding SSL for HTTPS & HTTP2
Building on the example above, we can activate additional modules to add support HTTPS and HTTP2 for the server.
To add HTTPS and HTTP2 connectors to a Jetty configuration, the modules can be activated by the following command:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
> java -jar $JETTY_HOME/start.jar --add-to-start=https,http2
@@ -169,7 +167,7 @@ The `--add-to-start` command sets up the effective command line in the ini files
You can configure the SSL connector to run on a different port by setting the `jetty.ssl.port` property on the command line:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
> cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar jetty.ssl.port=8444
@@ -183,7 +181,7 @@ Please see the section on link:#start-vs-startd[Start.ini vs. Start.d] for more
The job of the `start.jar` is to interpret the command line, `start.ini` and `start.d` directory (and associated .ini files) to build a Java classpath and list of properties and configuration files to pass to the main class of the Jetty XML configuration mechanism.
The `start.jar` mechanism has many options which are documented in the xref:startup[] administration section and you can see them in summary by using the command:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
> java -jar $JETTY_HOME/start.jar --help
----
diff --git a/jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-installing.adoc b/jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-installing.adoc
index 782e8d83cdac..c7a038ed987f 100644
--- a/jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-installing.adoc
+++ b/jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-installing.adoc
@@ -22,21 +22,21 @@
==== Downloading the Jetty Distribution
The standalone Jetty distribution is available for download from the Eclipse Foundation:
-____
+====
*Jetty*
https://www.eclipse.org/jetty/download.html
-____
+====
It is available in both zip and gzip formats; download the one most appropriate for your system.
When you download and unpack the binary, it is extracted into a directory called `jetty-distribution-VERSION.`
Put this directory in a convenient location.
The rest of the instructions in this documentation refer to this location as either `$JETTY_HOME` or as `$(jetty.home).`
-_____
[IMPORTANT]
+====
It is important that *only* stable releases are used in production environments.
Versions that have been deprecated or are released as Milestones (M) or Release Candidates (RC) are *not* suitable for production as they may contain security flaws or incomplete/non-functioning feature sets.
-_____
+====
[[distribution-content]]
===== Distribution Content
@@ -70,11 +70,10 @@ Jetty-Home is an alternate version of the distribution that contains only the ne
It is intended for advanced users who are already familiar with Jetty and want to download a smaller distribution package.
Jetty-Home can be downloaded from the Maven Central repository:
-____
+====
*Jetty-Home*
https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-home/
-____
-
+====
Like the main Jetty distribution, Jetty-Home is available in both zip and gzip formats; download the one most appropriate for your system.
Notice that there are a number of other files with extensions of .sha or .md5 which are checksum files.
When you download and unpack the binary, it is extracted into a directory called `jetty-home-VERSION.`
diff --git a/jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-running.adoc b/jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-running.adoc
index 7a5228a3be6d..7a3c10456f50 100644
--- a/jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-running.adoc
+++ b/jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-running.adoc
@@ -25,7 +25,7 @@ Jetty has no GUI (Graphical User Interface), so running the server and performin
Once you have access to your system's command line, navigate to the directory where you unpacked your copy of the Jetty distribution.
To start Jetty on the default port of 8080, run the following command:
-[source,screen,subs="{sub-order}"]
+[source,screen]
----
$ java -jar start.jar
2017-09-20 15:45:11.986:INFO::main: Logging initialized @683ms to org.eclipse.jetty.util.log.StdErrLog
@@ -43,14 +43,13 @@ To stop the server, press `CTRL` + `c` or `CTRL` + `z` in your terminal.
*Note* the `HomeBaseWarning` - it is *not* recommended to run Jetty from the `$JETTY_HOME` directory.
Instead, see how to link:#creating-jetty-base[create a Jetty Base] below.
-____
[NOTE]
+====
You will see examples throughout the documentation referencing `$JETTY_HOME` and `$JETTY_BASE` as well as `{jetty.home}` and `{jetty.base}`.
These terms are used to refer to the location of your Jetty installation directories.
Many users find it helpful to define `$JETTY_HOME` as an environment variable that maps to their Jetty distribution directory.
More information can be found in our Administration section on link:#startup-base-and-home[managing Jetty Home and Jetty Base.]
-____
-
+====
[[demo-webapps-base]]
==== Demo Base
@@ -58,7 +57,7 @@ Within the standard Jetty distribution there is the `demo-base` directory.
This is a fully-functioning Jetty Base (more on that later) complete with numerous web applications demonstrating different Jetty functionality.
Additionally, the `demo-base` demonstrates the recommended way to run a Jetty base in a directory separate from `$JETTY_HOME`:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
$ cd demo-base/
$ java -jar ../start.jar
@@ -103,14 +102,13 @@ $ java -jar ../start.jar
You can visit this demo server by pointing a browser at link:http://localhost:8080[], which will now show a welcome page and several demo/test web applications.
-____
[WARNING]
+====
The demonstration web applications are not necessarily secure and should *not* be deployed in production web servers.
-____
-
+====
You can see the configuration of the `demo-base` by using the following commands:
-[source, screen, subs="{sub-order}"]
+[source, screen]
----
> cd $JETTY_HOME/demo-base/
> java -jar $JETTY_HOME/start.jar --list-modules
diff --git a/jetty-documentation/src/main/asciidoc/quick-start/introduction/jetty-coordinates.adoc b/jetty-documentation/src/main/asciidoc/quick-start/introduction/jetty-coordinates.adoc
index be91400ef4a2..da528353898f 100644
--- a/jetty-documentation/src/main/asciidoc/quick-start/introduction/jetty-coordinates.adoc
+++ b/jetty-documentation/src/main/asciidoc/quick-start/introduction/jetty-coordinates.adoc
@@ -19,11 +19,11 @@
[[quickstart-jetty-coordinates]]
=== Finding Jetty in Maven
-_____
[IMPORTANT]
+====
It is important that only stable releases are used in production environments.
Versions that have been deprecated or are released as Milestones (M) or Release Candidates (RC) are not suitable for production as they may contain security flaws or incomplete/non-functioning feature sets.
-_____
+====
==== Maven Coordinates
@@ -33,7 +33,7 @@ With Jetty 7 the project moved to the Eclipse foundation and to a new `groupId`
The top level Project Object Model (POM) for the Jetty project is located under the following coordinates.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
@@ -49,7 +49,7 @@ Those generated files are also uploaded into Maven Central during the release of
https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-project/
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty
diff --git a/jetty-documentation/src/main/asciidoc/quick-start/introduction/what-version.adoc b/jetty-documentation/src/main/asciidoc/quick-start/introduction/what-version.adoc
index b8584fd1671c..d1f13e2dfcc8 100644
--- a/jetty-documentation/src/main/asciidoc/quick-start/introduction/what-version.adoc
+++ b/jetty-documentation/src/main/asciidoc/quick-start/introduction/what-version.adoc
@@ -23,11 +23,11 @@ Jetty 9 is the most recent version of Jetty and has a great many improvements ov
This documentation which focuses on Jetty 9.
While many people continue to use older versions of Jetty, we generally recommend using Jetty 9 as it represents the version of Jetty that we will actively maintain and improve over the next few years.
-_____
[IMPORTANT]
+====
It is important that only stable releases are used in production environments.
Versions that have been deprecated or are released as Milestones (M) or Release Candidates (RC) are not suitable for production as they may contain security flaws or incomplete/non-functioning feature sets.
-_____
+====
.Jetty Versions
[width="100%",cols="12%,9%,15%,6%,21%,10%,6%,21%",options="header",]
diff --git a/jetty-documentation/src/main/asciidoc/quick-start/part.adoc b/jetty-documentation/src/main/asciidoc/quick-start/part.adoc
index 8abb89bc358a..b410b8883f22 100644
--- a/jetty-documentation/src/main/asciidoc/quick-start/part.adoc
+++ b/jetty-documentation/src/main/asciidoc/quick-start/part.adoc
@@ -18,7 +18,7 @@
[[quick-start]]
-= Getting Started With Jetty
+== Getting Started With Jetty
include::introduction/chapter.adoc[]
include::getting-started/chapter.adoc[]
diff --git a/jetty-documentation/src/main/asciidoc/reference/architecture/basic-architecture.adoc b/jetty-documentation/src/main/asciidoc/reference/architecture/basic-architecture.adoc
index 666720d5c763..285b18c04fcb 100644
--- a/jetty-documentation/src/main/asciidoc/reference/architecture/basic-architecture.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/architecture/basic-architecture.adoc
@@ -25,7 +25,7 @@ The Jetty link:{JDURL}/org/eclipse/jetty/server/Server.html[Server] is the plumb
a collection of `Connector`s that accept connections and a collection of `Handler`s that
service requests from the connections and produce responses, with threads from a thread pool doing the work.
-image:images/jetty-high-level-architecture.png[image,width=576]
+image:reference/architecture/images/jetty-high-level-architecture.png[image,width=576]
While the Jetty request/responses are derived from the Servlet API, the full features of the Servlet API
are only available if you configure the appropriate handlers.
@@ -50,7 +50,7 @@ Most abstract concepts such as `Connector`s and `Handler`s are captured by inter
Generic handling for those interfaces is then provided in an abstract implementation
such as `AbstractConnector` and `AbstractHandler`.
-image:images/basic-architecture-patterns.png[image,width=576]
+image:reference/architecture/images/basic-architecture-patterns.png[image,width=576]
The JSR77 inspired life cycle of most Jetty components is represented by the `LifeCycle`
interface and the `AbstractLifeCycle` implementation used as the base of many Jetty components.
@@ -90,9 +90,9 @@ therefore using Jetty as a generic network server.
A `Handler` is the component that deals with HTTP requests and responses.
The core API of a handler is the handle method:
-image:images/basic-architecture-handlers.png[image,width=576]
+image:reference/architecture/images/basic-architecture-handlers.png[image,width=576]
-[source, java, subs="{sub-order}"]
+[source, java]
----
public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException
----
@@ -119,7 +119,7 @@ This gives three styles of Handler:
You can combine handlers to handle different aspects of a request by nesting them,
calling them in sequence, or by combining the two models.
-image:images/basic-architecture-nested-handlers.png[image,width=576]
+image:reference/architecture/images/basic-architecture-nested-handlers.png[image,width=576]
Handlers called in sequence perform actions that do not depend on the next invocation, nor on the handler order.
They handle a request and generate the response without interacting with other handlers.
@@ -136,7 +136,7 @@ See also xref:writing-custom-handlers[].
The `ServletHandler` is a `Handler` that generates content by passing the request to any
configured Servlet Filters and then to a Servlet mapped by a URI pattern.
-image:images/basic-architecture-servlet-handler.png[image,width=576]
+image:reference/architecture/images/basic-architecture-servlet-handler.png[image,width=576]
A `ServletHandler` is normally deployed within the scope of a `ServletContext`, which is a
`ContextHandler` that provides convenience methods for mapping URIs to servlets.
@@ -170,7 +170,7 @@ A `WebAppContext` is a derivation of `ServletContextHandler` that supports the s
of a web application and configuration of session, security, listeners, filter, servlets, and JSP
via a `web.xml` descriptor normally found in the `/WEB-INF` directory of a web application.
-image:images/basic-architecture-web-application.png[image,width=576]
+image:reference/architecture/images/basic-architecture-web-application.png[image,width=576]
Essentially `WebAppContext` is a convenience class that assists the construction and configuration
of other handlers to achieve a standard web application configuration.
diff --git a/jetty-documentation/src/main/asciidoc/reference/architecture/jetty-classloading.adoc b/jetty-documentation/src/main/asciidoc/reference/architecture/jetty-classloading.adoc
index 2b9c1c91e0c3..86073bf893a2 100644
--- a/jetty-documentation/src/main/asciidoc/reference/architecture/jetty-classloading.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/architecture/jetty-classloading.adoc
@@ -153,7 +153,7 @@ You can place additional Jars here.
You can add an additional classpath to a context classloader by calling link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html#setExtraClasspath(java.lang.String)[org.eclipse.jetty.webapp.WebAppContext.setExtraClasspath(String)] with a comma-separated list of paths.
You can do so directly to the API via a context XML file such as the following:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
...
@@ -172,7 +172,7 @@ Without this interface, session persistence will be slower.
You configure the classloader for the webapp like so:
-[source, java, subs="{sub-order}"]
+[source, java]
----
MyCleverClassLoader myCleverClassLoader = new MyCleverClassLoader();
...
@@ -190,14 +190,14 @@ You can also accomplish this in a context xml file.
If you start a Jetty server using a custom class loader–consider the Jetty classes not being available to the system class loader, only your custom class loader–you may run into class loading issues when the `WebAppClassLoader` kicks in.
By default the `WebAppClassLoader` uses the system class loader as its parent, hence the problem. This is easy to fix, like so:
-[source, java, subs="{sub-order}"]
+[source, java]
----
context.setClassLoader(new WebAppClassLoader(this.getClass().getClassLoader(), context));
----
or
-[source, java, subs="{sub-order}"]
+[source, java]
----
context.setClassLoader(new WebAppClassLoader(new MyCustomClassLoader(), context));
----
diff --git a/jetty-documentation/src/main/asciidoc/reference/architecture/server-side-architecture.adoc b/jetty-documentation/src/main/asciidoc/reference/architecture/server-side-architecture.adoc
index b79ab05d4549..95aa6ac3f508 100644
--- a/jetty-documentation/src/main/asciidoc/reference/architecture/server-side-architecture.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/architecture/server-side-architecture.adoc
@@ -89,7 +89,7 @@ It is trivial to write the synchronous version in terms of the asynchronous vers
You can use `EndPoint.write(Callback, ByteBuffer...)` in a blocking way as follows:
-[source, java, subs="{sub-order}"]
+[source, java]
----
FutureCallback callback = new FutureCallback();
endPoint.write(callback, buffers);
diff --git a/jetty-documentation/src/main/asciidoc/reference/contributing/coding-standards.adoc b/jetty-documentation/src/main/asciidoc/reference/contributing/coding-standards.adoc
index d02526759fb0..9aa845422029 100644
--- a/jetty-documentation/src/main/asciidoc/reference/contributing/coding-standards.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/contributing/coding-standards.adoc
@@ -37,7 +37,7 @@ http://git.eclipse.org/c/jetty/org.eclipse.jetty.admin.git/tree/jetty-eclipse-co
The following is an example of the Java formatting and naming styles to apply to Jetty:
-[source, java, subs="{sub-order}"]
+[source, java]
----
import some.exact.ClassName; // GOOD
diff --git a/jetty-documentation/src/main/asciidoc/reference/contributing/documentation.adoc b/jetty-documentation/src/main/asciidoc/reference/contributing/documentation.adoc
index d07cb039ff2a..9d277307c827 100644
--- a/jetty-documentation/src/main/asciidoc/reference/contributing/documentation.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/contributing/documentation.adoc
@@ -52,19 +52,19 @@ First you need to obtain the source of the documentation project.
Clone the repository:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ git clone https://github.com/eclipse/jetty.project.git
-....
+----
You will now have a local directory with all of jetty, including the jetty-documentation.
Now we move on to building it.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ cd jetty.project/jetty-documentation
$ mvn install
-....
+----
While maven is running you may see a lot of files being downloaded.
If you are not familiar with maven, then what you are seeing is maven setting up the execution environment for generating the documentation.
@@ -72,8 +72,8 @@ This build will first produce docbook xml and then through the docbkx-maven-plug
The downloads are all of the java dependencies that are required to make this build work.
After a while the downloading will stop and you should see the execution of the asciidoctor-maven-plugin followed by the docbkx-maven-plugin.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[INFO] --- asciidoctor-maven-plugin:1.5.3:process-asciidoc (output-html) @ jetty-documentation ---
[INFO] Rendered /Users/jesse/src/projects/jetty/jetty-docs/src/main/asciidoc/index.adoc
[INFO]
@@ -82,12 +82,12 @@ After a while the downloading will stop and you should see the execution of the
[INFO] Applying customization parameters
[INFO] Chunking output.
[INFO] See /Users/jesse/src/projects/jetty/jetty-docs/target/docbkx/html/index for generated file(s)
-....
+----
The build is finished once you see a message akin to this:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
@@ -95,16 +95,15 @@ The build is finished once you see a message akin to this:
[INFO] Finished at: Tue Oct 25 14:15:37 CDT 2011
[INFO] Final Memory: 14M/229M
[INFO] ------------------------------------------------------------------------
-....
+----
You may now open your web browser and browse to the first page of the html output to see what you have produced!
Generally you can do this with File -> Open File -> which will open a file system browsing screen, navigate to your jetty-documentation directory and then further into target/docbkx/html/index/index.html which is the first page of the produced documentation.
-____
[TIP]
+====
If the build is broken, feel free to notify us.
-____
-
+====
==== Making Changes
Now that you have built the documentation, you want to edit it and make some changes.
@@ -113,9 +112,9 @@ In the above example you have cloned directly from our canonical documentation r
Obviously we can not allow anyone immediate access to this repository so you must make a fork of it for your own and then issue back pull requests to build up documentation karma.
In English that means that you would go to the url of the documentation in github:
-....
+----
https://github.com/eclipse/jetty.project
-....
+----
When you are on this page you will see a little button called 'Fork' which you can click and you will be taken back to your main page on github where you have a new repository.
When you checkout this repository you are free to commit to your heart's delight all the changes you so direly wish to see in the Jetty documentation.
@@ -126,24 +125,23 @@ Now follow the process to push that change back into Jetty proper.
Do make sure the change works and the build isn't broken though so make sure you run maven and check the output.
Then commit the change.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ git commit -s -m "Tweaked the introduction to fix a horrid misspelled word." src/main/asciidoc/quickstart/introduction/topic.xml
-....
+----
-____
[NOTE]
+====
In order for us to accept your commit into the Jetty repository you must have an Eclipse CLA on file and sign your commit.
Please check out the link:#contributing-cla[patches] section for more information.
-____
-
+====
This will commit the change in your local repository.
You can then push the change up to your repository on github.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ git push
-....
+----
Now you'll see some output showing that your change has been propagated to your repository on github.
In fact if you navigate to that repository at the top of the files list you should see your comment there.
@@ -176,9 +174,9 @@ id's::
The id values go into a global namespace so they must be unique across the entire document or the last example will win and any cross links will go there.
Below is an example of an id.
-....
+----
[[this-id-an-id]]
-....
+----
link vs xref::
The `link:` item should be generally used for linking around the document when you want to choose the text that will be rendered in the link itself.
@@ -190,7 +188,7 @@ version differences::
license blocks::
Each adoc file should contain the license block that exists in the index.adoc file and a copy has been added to the bottom of this page as well for reference.
-....
+----
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
@@ -208,35 +206,36 @@ license blocks::
// You may elect to redistribute this code under either of these licenses.
// ========================================================================
//
-....
+----
Some admonition examples:
-______________________________________________
+
[NOTE]
+====
A note about the previous case to be aware of.
-______________________________________________
+====
-________________________________________
[IMPORTANT]
+====
Important notes are marked with an icon.
-________________________________________
+====
-________________________________
[TIP]
+====
Tips that make your life easier.
-________________________________
+====
-_______________________________________________________
[CAUTION]
+====
Places where you have to be careful what you are doing.
-_______________________________________________________
+====
-__________________________________________________________________________________________________________________
[WARNING]
+====
Where extreme care has to be taken. Data corruption or other nasty
things may occur if these warnings are ignored.
-__________________________________________________________________________________________________________________
+====
==== Oddities
diff --git a/jetty-documentation/src/main/asciidoc/reference/contributing/patches.adoc b/jetty-documentation/src/main/asciidoc/reference/contributing/patches.adoc
index c4f7ba4f5dac..279773366786 100644
--- a/jetty-documentation/src/main/asciidoc/reference/contributing/patches.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/contributing/patches.adoc
@@ -47,12 +47,11 @@ The Eclipse Foundation has a strong Intellectual Property policy which tracks co
A contributor needs to e-sign a Eclipse Contributor Agreement (for more explanation see the http://www.eclipse.org/legal/ecafaq.php[Eclipse ECA FAQ] ) regardless of how their contribution patch is provided.
You can familiarize yourself with the Eclipse wiki page at http://wiki.eclipse.org/Development_Resources/Contributing_via_Git[Contributing via Git].
In order to have a pull request accepted by any Eclipse project you *must* complete this agreement.
-____
[TIP]
+====
Log into the https://www.eclipse.org[Eclipse home page] (you will need to create an account with the Eclipse Foundation if you have not already done so), click on "Eclipse ECA", and complete the form.
Be sure to use the _same email address_ when you create any Git commit records.
-____
-
+====
[[contributing-git-config]]
==== Configuring Git
@@ -66,12 +65,11 @@ When making the commit for the pull request it is _vital_ that you "sign-off" o
Without this sign-off, your patch cannot be applied to the Jetty repository because it will be rejected.
You can check out the link:https://help.github.com/articles/signing-tags-using-gpg[guide at Github] for more information.
-____
[TIP]
+====
One way to think of this is that when you sign the ECA you are indicating that you are free to contribute to eclipse, but that doesn't mean everything you ever do can be contributed.
Using the commit signing mechanism indicates that your commit is under the auspices of your agreement.
-____
-
+====
If a pull request is for a particular issue in our repository then the format of the commit message is important.
The message should follow the form "Issue #123 ".
When the Jetty project runs releases we have an automated process that scans for commits with this format for inclusion in our VERSION.txt file.
diff --git a/jetty-documentation/src/main/asciidoc/reference/contributing/release-testing.adoc b/jetty-documentation/src/main/asciidoc/reference/contributing/release-testing.adoc
index d166162b7358..094addbaacae 100644
--- a/jetty-documentation/src/main/asciidoc/reference/contributing/release-testing.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/contributing/release-testing.adoc
@@ -23,23 +23,23 @@ To test a Jetty release, complete the following steps for each release you want
1. Download the staged release:
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
wget https://oss.sonatype.org/content/repositories/jetty-[reponumber]/org/eclipse/jetty/jetty-distribution/[jetty-version]/jetty-distribution-9.[jetty-minor-version].tar.gz
-....
+----
2. Extract to a directory of your choice.
3. Start jetty:
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
cd [installdir] ; java -jar start.jar
-....
+----
4. If there are no exceptions, proceed. Otherwise, investigate.
5. Open http://localhost:8080/ in a browser. In the examples section click "Test Jetty Webapp". You should see the `test.war` webapp.
6. Go through ALL the tests and verify that everything works as expected.
@@ -48,35 +48,35 @@ To test a Jetty release, complete the following steps for each release you want
9. In the examples section click "Servlet 3.1 Test" and verify that everything works as expected.
10. Verify that hot deployment works.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
cd [installdir] ;
touch [pathToJettyDistribution]/webapps.demo/test.xml
-....
+----
11. Verify that `test.war` gets redeployed in `STDOUT`.
12. Verify that the spdy example webapp and spdy-proxy do work
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
cd jetty_src/jetty-spdy/spdy-example-webapp
mvn jetty:run-forked
-....
+----
13. Browse to https://localhost:8443 and verify that all looks ok
14. Stop the server with CTRL+C and restart it in proxy mode:
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
mvn -Pproxy jetty:run-forked
-....
+----
15. Browse to http://localhost:8080 and https://localhost:8443 and verify that all looks ok
[[testing-cometd]]
@@ -84,17 +84,17 @@ To test a Jetty release, complete the following steps for each release you want
1. Clone CometD.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
clone git://github.com/cometd/cometd.git
git clone git://github.com/cometd/cometd.git
-....
+----
2. Edit `pom.xml` and update `jetty-version.`
+
-....
+----
UTF-8
@@ -111,16 +111,16 @@ To test a Jetty release, complete the following steps for each release you want
-....
+----
3. Build Cometd:
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
mvn clean install
-....
+----
4. Be patient.
5. Run the loadtest as it is described here: http://cometd.org/documentation/2.x/howtos/loadtesting.
Keep the default values, but make sure that you raise the clients setting to 1000.
@@ -128,8 +128,8 @@ Run the loadtest until ''JIT compilation time'' is close to a value of zero (abo
6. Make sure that the performance results are reasonably fast.
On a MacBook Pro i7 2.6ghz dualcore produces the following:
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
========================================
Statistics Started at Fri Mar 09 13:44:35 CET 2012
@@ -199,32 +199,32 @@ Messages - Network Latency Min/Ave/Max = 1/114/417 ms
Thread Pool - Concurrent Threads max = 239 | Queue Size max = 1002 | Queue Latency avg/max = 12/101 ms
-....
+----
7. Deploy `cometd.war` to the `webapps` directory of the jetty-distribution tested above.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
cp cometd-demo/target/cometd-demo-[version].war [pathToJetty]/jetty-distribution-[jetty-version]/webapps/
-....
+----
8. Start jetty and make sure there are no exceptions.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
cd [pathToJetty] && java -jar start.jar
-....
+----
9. Go through all pages of the demo and test them:
+
-....
+----
http://localhost:8080/cometd-demo-2.4.1-SNAPSHOT/
-....
+----
If all tests are green, you are done!
diff --git a/jetty-documentation/src/main/asciidoc/reference/contributing/releasing-jetty.adoc b/jetty-documentation/src/main/asciidoc/reference/contributing/releasing-jetty.adoc
index c098790779c9..494579307698 100644
--- a/jetty-documentation/src/main/asciidoc/reference/contributing/releasing-jetty.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/contributing/releasing-jetty.adoc
@@ -32,16 +32,16 @@ This release script is for jetty-9 (to release jetty-7 or jetty-8 see older docu
+
These follow a strict format and will be used when prompted during step link:#prepare-release-step[listitem_title] below.
+
-....
+----
Release Version : 9.0.0.v20130322 (v[year][month][day])
Next Development Version : 9.0.1-SNAPSHOT
Tag Name : jetty-9.9.0.v20130322
-....
+----
2. We use the 'release-9' branch to avoid problems with other developers actively working on the master branch.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
// Get all of the remotes
$ git pull origin
// Create a local tracking branch (if you haven't already)
@@ -51,58 +51,56 @@ $ git checkout release-9
// Merge from master into the branch (this becomes your point in time
// from master that you will be releasing from)
$ git merge --no-ff master
-....
+----
3. Update the VERSION.txt with changes from the git logs, this populates the resolves issues since the last release.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ mvn -N -Pupdate-version
-....
+----
4. Edit the VERSION.txt file to set the 'Release Version' at the top alongside the Date of this release.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ vi VERSION.txt
-....
+----
5. Make sure everything is commit'd and pushed to github.com/eclipse/jetty.project
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ git commit -m "Updating VERSION.txt top section" VERSION.txt
$ git push origin release-9
-....
+----
6. Prepare the Release
+
-____
[NOTE]
+====
This step updates the elements in the pom.xml files, does a test build with these new versions, and then commits the pom.xml changes to your local git repo.
The `eclipse-release` profile is required on the prepare in order to bring in the jetty aggregates as that profile defines a module which is ignored otherwise.
-____
-
+====
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ mvn release:prepare -DreleaseVersion=9.0.0.v20130322 \
-DdevelopmentVersion=9.0.1-SNAPSHOT \
-Dtag=jetty-9.0.0.v20130322 \
-Peclipse-release
-....
+----
7. Perform the Release
+
-____
[NOTE]
+====
This step performs the release and deploys it to a oss.sonatype.org staging repository.
-____
-
+====
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ mvn release:perform
-....
+----
8. Set up files for next development versions.
+
Edit `VERSION.txt` for 'Next Development Version' at the top.
@@ -110,12 +108,12 @@ Do not date this line.
+
Make sure everything is commit'd and pushed to github.com/eclipse/jetty.project
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ vi VERSION.txt
$ git commit -m "Updating VERSION.txt top section" VERSION.txt
$ git push origin release-9
-....
+----
9. Close the staging repository on oss.sonatype.org
@@ -126,12 +124,12 @@ $ git push origin release-9
* Release the staging repository to maven central on oss.sonatype.org
* Merge back the changes in release-9 to master
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ git checkout master
$ git merge --no-ff release-9
$ git push origin master
-....
+----
[[releasing-aggregates]]
==== Building and Deploying Aggregate Javadoc and Xref
@@ -142,12 +140,12 @@ If you don't know if you have access to this then you probably don't and will ne
To build and deploy the aggregate javadoc and jxr bits:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ cd target/checkout
$ mvn -Paggregate-site javadoc:aggregate jxr:jxr
$ mvn -N site:deploy
-....
+----
This will generate the aggregate docs and deploy them to the `/home/www/jetty//jetty-project` directory on download.eclipse.org.
@@ -167,10 +165,10 @@ To localize the scripts to your environment:
Once these are setup you can deploy a release to eclipse with the following incantation:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ ./promote-to-eclipse.sh 9.0.0.v20130322
-....
+----
Each of these scripts will download all of the relevant files from maven central and then copy them into the correct location on eclipse infrastructure.
On the eclipse side of it they will also adjust the xref and javadoc documentation links if they remain broken as well as regenerate all of the html files on the eclipse download site.
@@ -181,23 +179,23 @@ On the eclipse side of it they will also adjust the xref and javadoc documentati
Since we are not allowed to have symbolic links on the download site we have to log into the machine manually and remove the previous stable directory and update it with a new release.
Maintaining the conventions we use on the site will allow all 'stable' links to be stable and not needed to update to the latest major Jetty build version:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ ssh @build.eclipse.org
$ cd ~downloads/jetty/
$ rm -Rf stable-9
$ cp -r stable-9
$ ./index.sh
-....
+----
This needs to be done for all Eclipse Jetty releases (regardless of version). In addition we have to work to reduce the footprint of jetty on the primary eclipse download resources so we want to move older releases to the eclipse archive site.
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ cd ~/downloads/jetty
$ mv /home/data/httpd/archive.eclipse.org/jetty/
$ ./index.sh
-....
+----
Periodically we need to do the same for the osgi P2 repositories to keep the size of our downloads directory at a reasonable size.
@@ -249,9 +247,9 @@ Do the following steps to publish documentation for the release:
Make sure you follow the other examples and include the `rel="nofollow"` attribute on the link so that search engines do not crawl newly created documentation, otherwise we are subject to duplicate content penalties in SEO.
8. Commit the changes to the jetty-website project
-____
[NOTE]
+====
There is a separate Jenkins build job that publishes documentation to https://www.eclipse.org/jetty/documentation/current triggered by a push of changed files to the jetty-documentation project.
If you commit your change to the number from step 2, then these builds will use the same release version number.
It is preferable if you _don't_ commit that version number change, or better yet, ensure that it is set to the next -SNAPSHOT version number for your jetty major release number.
-____
+====
diff --git a/jetty-documentation/src/main/asciidoc/reference/contributing/source-build.adoc b/jetty-documentation/src/main/asciidoc/reference/contributing/source-build.adoc
index 332a085ea057..78dceb1b6498 100644
--- a/jetty-documentation/src/main/asciidoc/reference/contributing/source-build.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/contributing/source-build.adoc
@@ -55,25 +55,24 @@ Jetty uses http://maven.apache.org/[Apache Maven 3] for managing its build and p
Building Jetty should simply be a matter of changing into the relevant directory and executing the following commands:
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ git clone https://github.com/eclipse/jetty.project.git
$ cd jetty.project
$ mvn install
-....
+----
All relevant dependencies will be downloaded into your local repository automatically.
-____
[NOTE]
+====
Jetty has a great many test cases that run through the course of its build.
Periodically we find some test cases to be more time dependent than they should be and this results in intermittent test failures.
You can help track these down by opening a bug report.
-____
-
+====
==== Import into Eclipse
Jetty is a Maven project. To develop Jetty in Eclipse, follow these directions:
diff --git a/jetty-documentation/src/main/asciidoc/reference/debugging/debugging-with-eclipse.adoc b/jetty-documentation/src/main/asciidoc/reference/debugging/debugging-with-eclipse.adoc
index c59f38e9fbc9..7cd164b5a32d 100644
--- a/jetty-documentation/src/main/asciidoc/reference/debugging/debugging-with-eclipse.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/debugging/debugging-with-eclipse.adoc
@@ -30,15 +30,15 @@ Next we need to link the Eclipse project with the deployed webapp.
1. Within Eclipse, right-click on the project containing the webapp deployed into jetty and select *Debug -> Debug Configurations* and create a new configuration of **Remote Java Application**.
Make sure the port you choose is the same as the one you added in xref:enable-remote-debugging[].
+
-image:images/debug-eclipse-1.png[image,width=576]
+image:reference/debugging/images/debug-eclipse-1.png[image,width=576]
2. Next in your webapp you can set a breakpoint within a servlet which when it is tripped will halt the remote jvm's processing thread to await for debugging commands from your Eclipse instance.
+
-image:images/debug-eclipse-2.png[image,width=576]
+image:reference/debugging/images/debug-eclipse-2.png[image,width=576]
3. Accessing that servlet within your browser, pointed at your remote debug configurated jetty-distribution, should transition your Eclipse instance to the standard Debug view.
+
-image:images/debug-eclipse-3.png[image,width=576]
+image:reference/debugging/images/debug-eclipse-3.png[image,width=576]
[[eclipse-within-eclipse]]
==== Within Eclipse
@@ -49,11 +49,11 @@ The best place to get started on this approach is to look through xref:embedding
Once you have a main method defined in order to launch your application, right-click on the source file and select**Debug As -> Java Application**.
In your *Console* tab within Eclipse you should see your application startup and once it has completed startup you should be able to configure breakpoints and hit the Jetty instance as normal via your web browser.
-____
[TIP]
+====
You can easily configure logging through a `jetty-logging.properties`
file. If this file is on your classpath then Jetty will use it for
configuring logging, we use this approach extensively throughout Jetty
development and it makes life ever so much easier. You can see this in
action in the xref:configuring-jetty-stderrlog[] section.
-____
+====
diff --git a/jetty-documentation/src/main/asciidoc/reference/debugging/debugging-with-intellij.adoc b/jetty-documentation/src/main/asciidoc/reference/debugging/debugging-with-intellij.adoc
index 7e19c698314f..056ccf584f94 100644
--- a/jetty-documentation/src/main/asciidoc/reference/debugging/debugging-with-intellij.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/debugging/debugging-with-intellij.adoc
@@ -31,17 +31,17 @@ Next we need to link the IntelliJ project with the deployed webapp.
Add a new configuration by clicking the "+" icon. Choose **Remote**.
Make sure the port you choose is the same as the one you added in xref:enable-remote-debugging[].
+
-image:images/intellij_new_remote_config.png[image,width=800]
+image:reference/debugging/images/intellij_new_remote_config.png[image,width=800]
2. Next in your webapp you can set a breakpoint within a servlet which when it is tripped will halt the remote jvm's processing thread to await for debugging commands from your IntelliJ instance.
To set a breakpoint, simply open the servlet or any other class you want to debug and click left to the line you want to set the breakpoint at (where the red dot is on the next screenshot).
The red dot and red background on the line mark the breakpoint.
+
-image:images/intellij_set_breakpoint.png[image,width=800]
+image:reference/debugging/images/intellij_set_breakpoint.png[image,width=800]
3. Accessing that servlet within your browser, pointed at your remote debug configured jetty-distribution, should transition your IntelliJ instance to the standard debugger view.
+
-image:images/intellij_debug_view.png[image,width=800]
+image:reference/debugging/images/intellij_debug_view.png[image,width=800]
[[intellij-within-intellij]]
==== Within IntelliJ
@@ -55,15 +55,15 @@ In your *Console* tab within IntelliJ you should see your application startup an
The same thing works for unit tests.
Instead of the main method run debug on the test method you want to debug.
-image:images/intellij_select_debug.png[image,width=800]
+image:reference/debugging/images/intellij_select_debug.png[image,width=800]
Debugging in IntelliJ is extremely powerful.
For example it's possible to have conditional breakpoints that only trigger a break if the configured conditions are met.
Have a look at the various tutorials in the internet or the http://www.jetbrains.com/idea/webhelp/getting-help.html[IntelliJ documentation] for further details.
-____
[TIP]
+====
You can easily configure logging through a `jetty-logging.properties` file.
If this file is on your classpath then Jetty will use it for configuring logging, we use this approach extensively throughout Jetty development and it makes life ever so much easier.
You can see this in action in the xref:configuring-jetty-stderrlog[] section.
-____
+====
diff --git a/jetty-documentation/src/main/asciidoc/reference/debugging/enable-remote-debugging.adoc b/jetty-documentation/src/main/asciidoc/reference/debugging/enable-remote-debugging.adoc
index f1f7a90bf6eb..7e36f6e53530 100644
--- a/jetty-documentation/src/main/asciidoc/reference/debugging/enable-remote-debugging.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/debugging/enable-remote-debugging.adoc
@@ -26,11 +26,10 @@ If you have a web application deployed into Jetty you can interact with it remot
The basics are that you must start up the remote JVM with additional parameters and then start up a remote debugging session in Eclipse for the webapp in question.
This is easily accomplished.
-____
[NOTE]
+====
This example assumes you are deploying your web application into the jetty-distribution.
-____
-
+====
===== Starting Jetty
Assuming you have your webapp deployed into jetty, there are two different ways to approach this:
@@ -38,13 +37,13 @@ Assuming you have your webapp deployed into jetty, there are two different ways
Via command line::
Add the required parameters on the commandline like so.
+
-[source, screen, subs="{sub-order}"]
-....
+[source, screen]
+----
$ java -Xdebug -agentlib:jdwp=transport=dt_socket,address=9999,server=y,suspend=n -jar start.jar
-....
+----
Via `start.ini`::
This approach is best used if you want to debug a particular jetty-distribution and not have to remember the commandline incantations.
@@ -52,7 +51,7 @@ Via `start.ini`::
1. Edit the `start.ini` and uncomment the --exec line, this is required if you are adding jvm options to the start.ini file as jetty-start must generate the classpath required and fork a new jvm.
2. Add the parameters mentioned above in the Command Line option so your start.ini looks like this:
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
#===========================================================
# Configure JVM arguments.
@@ -86,7 +85,7 @@ Uncomment any other jvm environmental options you so desire for your debugging s
3. Regardless of the option chosen, you should see the following lines at the top of your jetty-distribution startup.
+
-[source, plain, subs="{sub-order}"]
+[source, plain]
----
Listening for transport dt_socket at address: 9999
diff --git a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-env-xml.adoc b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-env-xml.adoc
index 9f08ccf30304..55d9e2b7048e 100644
--- a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-env-xml.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-env-xml.adoc
@@ -30,7 +30,7 @@ You define global naming resources on the server via `jetty.xml`.
Jetty applies `jetty-env.xml` on a per-webapp basis, and configures an instance of `org.eclipse.jetty.webapp.WebAppContext.`
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -43,17 +43,16 @@ Jetty applies `jetty-env.xml` on a per-webapp basis, and configures an instance
----
-____
[CAUTION]
+====
Make sure you are applying the configuration to an instance of the proper class. `jetty-env.xml` configures an instance of WebAppContext, and not an instance of Server.
-____
-
+====
[[using-jetty-env-xml]]
==== Using `jetty-env.xml`
Place the `jetty-env.xml` file in your web application's WEB-INF folder.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
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 3b5b7a4d902a..90b78382ce54 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,7 +30,7 @@ For a more in-depth look at the syntax, see xref:jetty-xml-syntax[].
`jetty-web.xml` applies on a per-webapp basis, and configures an instance of `org.eclipse.jetty.webapp.WebAppContext`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -40,11 +40,10 @@ For a more in-depth look at the syntax, see xref:jetty-xml-syntax[].
----
-____
[CAUTION]
+====
Make sure you are applying the configuration to an instance of the proper class. `jetty-web.xml` configures an instance of `WebAppContext`; `jetty.xml` configures an instance of `Server`.
-____
-
+====
[[using-jetty-web-xml]]
==== Using jetty-web.xml
@@ -52,11 +51,10 @@ Place the `jetty-web.xml` into your web application's `WEB-INF` folder.
When Jetty deploys a web application, it looks for a file called `WEB-INF/jetty-web.xml` or `WEB-INF/web-jetty.xml` within the web application (or WAR) and applies the configuration found there.
Be aware that `jetty-web.xml` is called _after_ all other configuration has been applied to the web application.
-____
[IMPORTANT]
+====
It is important to note that `jetty-web.xml` files utilize the webapp classpath, not the classpath of the server.
-____
-
+====
[[jetty-web-xml-examples]]
==== jetty-web.xml Examples
diff --git a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-config.adoc b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-config.adoc
index 632c9cab230b..56a9206a2d45 100644
--- a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-config.adoc
+++ b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-config.adoc
@@ -39,7 +39,7 @@ The selection of which configuration files to use is controlled by `start.jar` a
`jetty.xml` configures an instance of the `Jetty org.eclipse.jetty.server.Server.`
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
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 e5562a748bfe..5980f7d83121 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
@@ -31,7 +31,7 @@ See configuration files for specific examples.
The following XML configuration file creates some Java objects and sets some attributes:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -60,7 +60,7 @@ The following XML configuration file creates some Java objects and sets some att
The XML above is equivalent to the following Java code:
-[source, java, subs="{sub-order}"]
+[source, java]
----
com.acme.Foo foo = new com.acme.Foo();
foo.setName("demo");
@@ -86,7 +86,7 @@ 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:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -101,7 +101,7 @@ Files that conform to the configure.dtd format are processed in Jetty by the `Xm
To ensure your `web.xml`, `web-fragment.xml` and `webdefault.xml` files are validated, you will also need to set the `validateXml` attribute to true:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
org.eclipse.jetty.webapp.validateXml
@@ -115,7 +115,7 @@ The configuration of object instances with Jetty IoC XML is done on a scoped bas
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}"]
+[source, xml]
----
value
@@ -157,14 +157,14 @@ The ID must be unique for each object you create.
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:
-....
+----
result
org.example.SomeClass
@@ -172,12 +172,12 @@ Thus, the more verbose element style is available and the following is semantica
value0
value1
-....
+----
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:
-....
+----
@@ -185,7 +185,7 @@ It is possible to use a mix of styles and the following example shows a moretypi
value0
value1
-....
+----
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.
@@ -222,7 +222,7 @@ link:#jetty-xml-property[Property element]
====== Basic Example
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
8080
@@ -231,7 +231,7 @@ link:#jetty-xml-property[Property element]
This is equivalent to:
-[source, java, subs="{sub-order}"]
+[source, java]
----
org.eclipse.jetty.server.Server server = new org.eclipse.jetty.server.Server();
server.setPort(8080);
@@ -241,7 +241,7 @@ server.setPort(8080);
In `etc/jetty.xml`:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -250,7 +250,7 @@ In `etc/jetty.xml`:
In `etc/jetty-logging.xml`:
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -259,9 +259,9 @@ In `etc/jetty-logging.xml`:
Then run the combined configuration using:
-....
+----
java -jar start.jar etc/jetty.xml jetty-logging.xml
-....
+----
[[jetty-xml-set]]
====
@@ -298,7 +298,7 @@ link:#jetty-xml-property[Property element]
====== Basic Example
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
8080
@@ -307,7 +307,7 @@ link:#jetty-xml-property[Property element]
====== Set via a System Property
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -316,7 +316,7 @@ link:#jetty-xml-property[Property element]
====== Creating a NewObject and Setting It on the Server
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -330,7 +330,7 @@ link:#jetty-xml-property[Property element]
This is equivalent to:
-[source, java, subs="{sub-order}"]
+[source, java]
----
org.eclipse.jetty.server.Server server = new org.eclipse.jetty.server.Server();
@@ -343,7 +343,7 @@ server.setThreadPool(threadPool);
====== Invoking a Static Setter
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
loggerName
@@ -385,7 +385,7 @@ link:#jetty-xml-property[Property element]
This simple example doesn't do much on its own.
You would normally use this in conjunction with a `]`.
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -394,7 +394,7 @@ You would normally use this in conjunction with a ``.
====== Invoking a Static Getter and Call Methods on the Returned Object
-[source, xml, subs="{sub-order}"]
+[source, xml]
----
@@ -432,7 +432,7 @@ link:#jetty-xml-property[Property element]
===== Example
-[source, xml, subs="{sub-order}"]
+[source, xml]
----