From 76b7686bc73ed18ea5a48e87b5dd97d4e54e3333 Mon Sep 17 00:00:00 2001
From: Jan Bartel <janb@webtide.com>
Date: Fri, 25 Nov 2016 14:47:41 +1100
Subject: [PATCH] Issue #1117

---
 .../deploying/quickstart-webapp.adoc          | 22 ++++++++++++++++++-
 .../development/maven/jetty-maven-plugin.adoc | 21 +++++++++++++++++-
 2 files changed, 41 insertions(+), 2 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 c7cacca4760..b6c457ce482 100644
--- a/jetty-documentation/src/main/asciidoc/configuring/deploying/quickstart-webapp.adoc
+++ b/jetty-documentation/src/main/asciidoc/configuring/deploying/quickstart-webapp.adoc
@@ -31,7 +31,6 @@ 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
 
@@ -71,6 +70,27 @@ 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.
+originAttribute::
+                   The name of an attribute to insert into the generated elements in quickstart-web.xml that gives the origin of the element.
+                   By default it is `origin`.
+generateOrigin::
+                    (true/false).
+                    By default it is `false`.
+                    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.
+
+
+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}"]
+----
+<listener origin="DefaultsDescriptor(file:///path/to/distro/etc/webdefault.xml):21">
+<listener origin="WebDescriptor(file:///path/to/base/webapps/test-spec/WEB-INF/web.xml):22">
+<servlet-class origin="FragmentDescriptor(jar:file:///path/to/base/webapps/test-spec/WEB-INF/lib/test-web-fragment.jar!/META-INF/web-fragment.xml):23">
+<servlet-class origin="@WebServlet(com.acme.test.TestServlet):24">
+----
 
 ====== 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.
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 2edd474e926..a319546f116 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
@@ -727,6 +727,7 @@ If this is not the case, you will get an "Address already in use" error message
 ==== 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`).
+Note that no programmatic declarations of servlets, filters and listeners can be taken into account.
 The effective `web.xml` from these combined sources is generated and displayed as maven log output.
 Other useful information about your webapp that is produced as part of the analysis is also stored as context parameters in the effective-web.xml.
 The effective-web.xml can be used in conjunction with the link:#quickstart-webapp[Quickstart] feature to quickly start your webapp (note that Quickstart is not appropriate for the mvn jetty goals).
@@ -739,7 +740,25 @@ If set to `false`, the effective web.xml is generated into a file called `effect
 effectiveWebXml::
 The full path name of a file into which you would like the effective web xml generated.
 
-Note that no programmatic declarations of servlets, filters and listeners will be taken into account.
+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}"]
+----
+<listener origin="DefaultsDescriptor(file:///path/to/distro/etc/webdefault.xml):21">
+<listener origin="WebDescriptor(file:///path/to/base/webapps/test-spec/WEB-INF/web.xml):22">
+<servlet-class origin="FragmentDescriptor(jar:file:///path/to/base/webapps/test-spec/WEB-INF/lib/test-web-fragment.jar!/META-INF/web-fragment.xml):23">
+<servlet-class origin="@WebServlet(com.acme.test.TestServlet):24">
+----
+
+To generate origin informatino, use the following configuration parameters on the  `webApp` element:
+
+originAttribute::
+The name of the attribute that will contain the origin.
+By default it is `origin`.
+generateOrigin::
+False by default. If true, will force the generation of the originAttribute onto each element.
+
 
 [[using-overlaid-wars]]
 ==== Using Overlaid wars