From c1c42f6b7344c3a0c5283ef6d1fef942d5a0e588 Mon Sep 17 00:00:00 2001 From: WalkerWatch Date: Thu, 29 Sep 2016 11:53:06 -0400 Subject: [PATCH] Updates quickstart docs for #896 Signed-off-by: WalkerWatch --- .../deploying/quickstart-webapp.adoc | 22 ++++++++++++++++--- .../development/maven/jetty-maven-plugin.adoc | 1 + 2 files changed, 20 insertions(+), 3 deletions(-) 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 a9c15ea735d..03e859267f9 100644 --- a/jetty-documentation/src/main/asciidoc/configuring/deploying/quickstart-webapp.adoc +++ b/jetty-documentation/src/main/asciidoc/configuring/deploying/quickstart-webapp.adoc @@ -21,7 +21,7 @@ The auto discovery features of the Servlet specification can make deployments sl Auto discovery of Web Application configuration can be useful during the development of a webapp as it allows new features and frameworks to be enabled simply by dropping in a jar file. However, for deployment, the need to scan the contents of many jars can have a significant impact of the start time of a webapp. -From Jetty release 9.2.0.v20140526, the included quickstart module allows a webapp to be pre-scanned and preconfigured. +With the release of Jetty 9.2, a quickstart module was included which allows a webapp to be pre-scanned and preconfigured. This means that all the scanning is done prior to deployment and all configuration is encoded into an effective `web.xml`, called `WEB-INF/quickstart-web.xml`, which can be inspected to understand what will be deployed before deploying. Not only does the `quickstart-web.xml` contain all the discovered Servlets, Filters and Constraints, but it also encodes as context parameters all discovered: @@ -35,7 +35,6 @@ Tests have shown that webapps that took many seconds to scan and deploy can now ==== Setting up Quickstart To use quickstart the module has to be available to the Jetty instance. -In a maven project this is done by adding a dependency on the artifact ID `jetty-quickstart`. In a standard Jetty distribution it can be configured with the following command: [source, screen, subs="{sub-order}"] @@ -43,8 +42,22 @@ In a standard Jetty distribution it can be configured with the following command $ java -jar $JETTY_HOME/start.jar --add-to-startd=quickstart ---- +In a Maven project this is done by adding a dependency on the artifact ID `jetty-quickstart`. + +[source, xml, subs="{sub-order}"] +---- + + org.eclipse.jetty + jetty-quickstart + {VERSION} + +---- + +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. +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: [source, xml, subs="{sub-order}"] @@ -58,6 +71,9 @@ Otherwise, create a `webapps/myapp.xml` file as follows: ---- +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. + // ==== Preconfiguring the web application // // If the `QuickStateWebApp` method `setAutoPreconfigure(true)` is called (see example in myapp.xml above), then the first time the webapp is deployed a `WEB-INF/quickstart-web.xml` file will be generated that contains the effective `web.xml` for all the discovered configuration. 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 c0db940dcea..2edd474e926 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 @@ -723,6 +723,7 @@ 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. +[[jetty-effective-web-xml]] ==== jetty:effective-web-xml This goal calculates a synthetic `web.xml` (the "effective web.xml") according to the rules of the Servlet Specification taking into account all sources of discoverable configuration of web components in your application: descriptors (`webdefault.xml`, `web.xml`, `web-fragment.xml`s, `web-override.xml`) and discovered annotations (`@WebServlet`, `@WebFilter`, `@WebListener`).