Issue #896

jetty-documentation/src/main/asciidoc/configuring/deploying/quickstart-webapp.adoc

@@ -31,18 +31,24 @@ Not only does the `quickstart-web.xml` contain all the discovered Servlets, Filt
 
 With the quickstart mechanism, Jetty is able to entirely bypass all scanning and discovery modes and start a webapp in a predictable and fast way.
 Tests have shown that webapps that took many seconds to scan and deploy can now be deployed in a few hundred milliseconds.
+Additionally, if debug logging is enabled, the generated quickstart information is tagged with the origin of every element, which can be useful for debugging purposes. 
 
 ==== Setting up Quickstart
 
-To use quickstart the module has to be available to the Jetty instance.
+===== Prerequisites 
-In a standard Jetty distribution it can be configured with the following command:
+
+====== Jetty Distribution
+
+In a standard Jetty distribution the quickstart module can be configured with the following command:
 
 [source, screen, subs="{sub-order}"]
 ----
 $ java -jar $JETTY_HOME/start.jar --add-to-start=quickstart
 ----
 
-In a Maven project this is done by adding a dependency on the artifact ID `jetty-quickstart`.
+====== Embedded
+
+In a Maven project you add a dependency on the artifact `jetty-quickstart`.
 
 [source, xml, subs="{sub-order}"]
 ----
@@ -53,26 +59,62 @@ In a Maven project this is done by adding a dependency on the artifact ID `jetty
 </dependency>
 ----
 
-Additionally, for those using Maven, the link:#get-up-and-running[Jetty Maven Plugin] has a goal, link:#jetty-effective-web-xml[`jetty:effective-web-xml`], which performs quickstart operations.
-It should be noted, however, that the Jetty Maven Plugin also includes additional items on it's classpath which may not be needed by the webapp.
 
-Deployed webapps need to be instances of link:{JDURL}/org/eclipse/jetty/quickstart/QuickStartWebApp.html[`org.eclipse.jetty.quickstart.QuickStartWebApp`] rather than the normal `org.eclipse.jetty.webapp.WebAppContext`.
+
-If a web application already has a `webapps/myapp.xml` file, simply change the class in the `Configure` element.
+===== Configuration
-Otherwise, create a `webapps/myapp.xml` file as follows:
+
+Webapps need to be instances of link:{JDURL}/org/eclipse/jetty/quickstart/QuickStartWebApp.html[`org.eclipse.jetty.quickstart.QuickStartWebApp`] rather than the normal `org.eclipse.jetty.webapp.WebAppContext`.
+
+`org.eclipse.jetty.quickstart.QuickStartWebApp` instances offer the same setters as the familiar `org.eclipse.jetty.webapp.WebAppContext`, with the addition of:
+
+autoPreconfigure:: 
+                   (true/false). 
+                   If true, the first time the webapp is run, the WEB-INF/quickstart-web.xml is generated BEFORE the webapp is deployed.
+                   Subsequent runs use the previously generated quickstart file.
+
+====== In XML
+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}"]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">
+<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
 <Configure class="org.eclipse.jetty.quickstart.QuickStartWebApp">
-  <Set name="war"><Property name="jetty.webapps" default="."/>/benchmark.war</Set>
-  <Set name="contextPath">/benchmark</Set>
   <Set name="autoPreconfigure">true</Set>
 </Configure>
 ----
 
-For embedded implementations of Jetty, invoking the link:{JDURL}/org/eclipse/jetty/quickstart/PreconfigureQuickStartWar.html[`org.eclipse.jetty.quickstart.PreconfigureQuickStartWar`] class can be used to configure war files for quickstart deployment.
+====== In Code
-This will create the `quickstart-web.xml` before the first deployment.
+
+Create an instance of link:{JDURL}/org/eclipse/jetty/quickstart/QuickStartWebApp.html[`org.eclipse.jetty.quickstart.QuickStartWebApp`] rather than the normal `org.eclipse.jetty.webapp.WebAppContext`. You then use the QuickStartWebApp instance in exactly the same way that you would a WebAppContext.
+
+Here's a snippet:
+
+[source, java]
+----
+    QuickStartWebApp webapp = new QuickStartWebApp();
+    webapp.setAutoPreconfigure(true);
+----
+
+
+====== Pre-generating the quickstart-web.xml file
+
+Rather than use the `autoPreconfigure` feature of the QuickStartWebApp - which lazily generates the `quickstart-web.xml` file - you can eagerly pre-generate it for an existing war by invoking as a main class link:{JDURL}/org/eclipse/jetty/quickstart/PreconfigureQuickStartWar.html[`org.eclipse.jetty.quickstart.PreconfigureQuickStartWar`]. 
+Note that you will need to provide all necessary jetty jars on the command line classpath.
+This will unpack the war if necessary, and create the `quickstart-web.xml` before the first deployment:
+
+
+[source, screen, subs="{sub-order}"]
+----
+$ java -cp [jetty classpath] org.eclipse.jetty.quickstart.PreconfigureQuickStartWar myapp.war
+----
+
+Run the class with no arguments to see other runtime options.
+
+Alternatively, you could use the link:#get-up-and-running[Jetty Maven Plugin] goal link:#jetty-effective-web-xml[`jetty:effective-web-xml`]: this will generate quickstart information, but print it to stderr. 
+The goal provides a configuration option to save the output to a file, which you can then copy into your webapp's WEB-INF dir.
+Note that as the Jetty Maven Plugin is a general tool for running webapps, it may have more jars on its classpath than are needed by your application, and thus may generate extra quickstart information: we recommend that you use this goal only as a quick guide to the type of information that quickstart generates.
 
 // ==== Preconfiguring the web application
 //
@@ -81,14 +123,8 @@ This will create the `quickstart-web.xml` before the first deployment.
 //
 // It is also possible to preconfigure a war file manually by running the class link:{JDURL}/org/eclipse/jetty/quickstart/PreconfigureQuickStartWar.html[org.eclipse.jetty.quickstart.PreconfigureQuickStartWar] with the jetty-all-uber (aggregate) jar:
 //
-// [source, screen, subs="{sub-order}"]
-// ----
-// $ java -cp jetty-all-{VERSION}-uber.jar org.eclipse.jetty.quickstart.PreconfigureQuickStartWar myapp.war
-// ----
 //
 // This will create the `quickstart-web.xml` file before the first deployment.
-// Note that this can also be a good debugging tool for discovered configuration and if run with debug turned on the origin of every element is included in the `quickstart-web.xml` file.
-// Run the class with no arguments to see other runtime options.
 
 ==== Avoiding TLD Scans with precompiled JSPs