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 b3651c24f4b..c7cacca4760 100644 --- a/jetty-documentation/src/main/asciidoc/configuring/deploying/quickstart-webapp.adoc +++ b/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. -In a standard Jetty distribution it can be configured with the following command: +===== Prerequisites + +====== 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 ---- -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. -Otherwise, create a `webapps/myapp.xml` file as follows: + +===== Configuration + +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}"] ---- - + - /benchmark.war - /benchmark true ---- -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. -This will create the `quickstart-web.xml` before the first deployment. +====== In Code + +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