From 3e43ffe64188bcacd9050954cc1428c1ea58945c Mon Sep 17 00:00:00 2001 From: WalkerWatch Date: Wed, 30 Nov 2016 13:38:17 -0500 Subject: [PATCH] Issue #1138 - Doc updates and cleanup. Signed-off-by: WalkerWatch --- ...onfiguring-specific-webapp-deployment.adoc | 10 +++++---- .../reference/contributing/patches.adoc | 4 ++-- .../reference/jetty-xml/jetty-env-xml.adoc | 22 +++++++++---------- .../jetty-xml/jetty-web-xml-config.adoc | 4 ++-- .../reference/jetty-xml/jetty-xml-config.adoc | 4 ++-- .../reference/jetty-xml/jetty-xml-syntax.adoc | 11 ++++++++++ .../reference/jetty-xml/jetty-xml-usage.adoc | 2 +- .../reference/jetty-xml/override-web-xml.adoc | 2 +- .../reference/jetty-xml/webdefault-xml.adoc | 14 +++++++----- 9 files changed, 44 insertions(+), 29 deletions(-) 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 d10f586cbf5..a2cd3f1560d 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 @@ -52,11 +52,8 @@ For example, here is a descriptor file that deploys the file `/opt/myapp/myapp.w ---- -____ -[NOTE] 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}"] ---- @@ -72,6 +69,11 @@ ____ 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 @@ -130,7 +132,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. +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}"] diff --git a/jetty-documentation/src/main/asciidoc/reference/contributing/patches.adoc b/jetty-documentation/src/main/asciidoc/reference/contributing/patches.adoc index e0f586e7e43..6aa30846471 100644 --- a/jetty-documentation/src/main/asciidoc/reference/contributing/patches.adoc +++ b/jetty-documentation/src/main/asciidoc/reference/contributing/patches.adoc @@ -30,8 +30,8 @@ The following is the general process by which we operate. * This may not be the final form a commit will take, there may be some back and forth and you may be asked to re-issue a pull request. - -Not everything is specifically relevant since we are at GitHub but the crux of things are detailed there. The CLA is critically important to the process. +Not everything is specifically relevant since we are at GitHub but the crux of things are detailed there. +The CLA is *critically* important to the process. [[contributing-cla]] ==== Sign a CLA 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 4e9b3269ffd..2ab4117cd96 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 @@ -15,7 +15,7 @@ // ======================================================================== [[jetty-env-xml]] -=== `jetty-env.xml` +=== jetty-env.xml `jetty-env.xml` is an optional Jetty file that configures JNDI resources for an individual webapp. The format of `jetty-env.xml` is the same as xref:jetty-xml-config[] –it is an XML mapping of the Jetty API. @@ -24,13 +24,13 @@ When Jetty deploys a web application, it automatically looks for a file called ` You define global naming resources on the server via `jetty.xml`. [[jetty-env-root-element]] -==== `jetty-env.xml` Root Element +==== jetty-env.xml Root Element 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}"] ---- - + @@ -38,7 +38,7 @@ Jetty applies `jetty-env.xml` on a per-webapp basis, and configures an instance .. - + ---- ____ @@ -53,26 +53,26 @@ Place the `jetty-env.xml` file in your web application's WEB-INF folder. [source, xml, subs="{sub-order}"] ---- - + - + - + gargle 100 true - + wiggle 55.0 true - + jdbc/mydatasource99 @@ -87,11 +87,11 @@ Place the `jetty-env.xml` file in your web application's WEB-INF folder. - + ---- [[additional-jetty-env-xml-resources]] -==== Additional `jetty-env.xml` Resources +==== Additional jetty-env.xml Resources * xref:jetty-xml-syntax[] –In-depth reference for Jetty-specific configuration XML syntax. * xref:jetty-xml-config[] –Configuration file for configuring the entire server. 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 4d42bfb6b49..42ca5130675 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 @@ -15,7 +15,7 @@ // ======================================================================== [[jetty-web-xml-config]] -=== `jetty-web.xml` +=== jetty-web.xml `jetty-web.xml` is a Jetty configuration file that you can bundle with a specific web application. The format of `jetty-web.xml` is the same as xref:jetty-xml-config[] – it is an XML mapping of the Jetty API. @@ -44,7 +44,7 @@ Make sure you are applying the configuration to an instance of the proper class. ____ [[using-jetty-web-xml]] -==== Using `jetty-web.xml` +==== Using jetty-web.xml 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. 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 1849e82f623..89755ea5ebb 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 @@ -15,7 +15,7 @@ // ======================================================================== [[jetty-xml-config]] -=== `jetty.xml` +=== jetty.xml `jetty.xml` is the default configuration file for Jetty, typically located at ` $JETTY_HOME/etc/jetty.xml`. Usually the `jetty.xml` configures: @@ -47,7 +47,7 @@ The selection of which configuration files to use is controlled by xref:advanced ... - + ---- [[jetty-xml-examples]] 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 cae32fe2abb..fec75e8eef9 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 @@ -77,6 +77,7 @@ bar.getParent().setName("demo2"); ==== Overview +[[jetty-xml-dtd]] ===== Understanding DTD and Parsing The document type descriptor @@ -96,6 +97,16 @@ The URL may point to configure.dtd if you want the latest current version, or to Files that conform to the configure.dtd format are processed in Jetty by the `XmlConfiguration` class which may also validate the XML (using a version of the DTD from the classes jar file), but is by default run in a forgiving mode that tries to work around validation failures. +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}"] +---- + + org.eclipse.jetty.webapp.validateXml + true + +---- + ===== Jetty XML Configuration Scope The configuration of object instances with Jetty IoC XML is done on a scoped basis, so that for any given XML element there is a corresponding Object in scope and the nested XML elements apply to that. diff --git a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-usage.adoc b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-usage.adoc index c86edafe06e..1966bb9bd9c 100644 --- a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-usage.adoc +++ b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/jetty-xml-usage.adoc @@ -22,7 +22,7 @@ It is grounded in Java's Reflection API. Classes in the `java.lang.reflect` repr Behind the scenes, Jetty's XML config parser translates the XML elements and attributes into Reflection calls. [[using-jettyxml]] -==== Using `jetty.xml` +==== Using jetty.xml To use `jetty.xml`, specify it as a configuration file when running Jetty. diff --git a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/override-web-xml.adoc b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/override-web-xml.adoc index 60f26ea37df..8c65c613973 100644 --- a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/override-web-xml.adoc +++ b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/override-web-xml.adoc @@ -15,7 +15,7 @@ // ======================================================================== [[override-web-xml]] -=== Jetty `override-web.xml` +=== Jetty override-web.xml To deploy a web application or WAR into different environments, most likely you will need to customize the webapp for compatibility with each environment. The challenge is to do so without changing the webapp itself. You can use a `jetty.xml` file for some of this work since it is not part of the webapp. diff --git a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/webdefault-xml.adoc b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/webdefault-xml.adoc index 588f5b56a8b..88b6b11c97f 100644 --- a/jetty-documentation/src/main/asciidoc/reference/jetty-xml/webdefault-xml.adoc +++ b/jetty-documentation/src/main/asciidoc/reference/jetty-xml/webdefault-xml.adoc @@ -15,7 +15,7 @@ // ======================================================================== [[webdefault-xml]] -=== `webdefault.xml` +=== webdefault.xml The `webdefault.xml` file saves web applications from having to define a lot of house-keeping and container-specific elements in their own `web.xml` files. For example, you can use it to set up mime-type mappings and JSP servlet-mappings. @@ -27,12 +27,17 @@ However, it is certainly possible to provide differentiated ` webdefault.xml` fi The `webdefault.xml` file is located in `$(jetty.home)/etc/webdefault.xml`. [[using-webdefault-xml]] -==== Using `webdefault.xml` +==== Using webdefault.xml You can specify a custom configuration file to use for specific webapps, or for all webapps. If you do not specify an alternate defaults descriptor, the $JETTY-HOME/etc/jetty-deploy.xml file will configure jetty to automatically use $JETTY_HOME/etc/`webdefault.xml`. +____ +[NOTE] +To ensure your `webdefault.xml` files are validated, you will need to set the `validateXml` attribute to true as described link:#jetty-xml-dtd[here.] +____ + [[creating-custom-webdefault-xml-one-webapp]] -===== Creating a Custom `webdefault.xml` for One WebApp +===== Creating a Custom webdefault.xml for One WebApp You can specify a custom `webdefault.xml` for an individual web application in that webapp's xref:jetty-xml-config[] as follows: @@ -63,8 +68,6 @@ import org.eclipse.jetty.webapp.WebAppContext; //Set up the absolute path to the custom webdefault.xml. wac.setDefaultsDescriptor("/my/path/to/webdefault.xml"); ... - - ---- Alternatively, you can use a xref:jetty-classloading[] to find the resource representing your custom `webdefault.xml`. @@ -86,7 +89,6 @@ Similarly, when using the link:#jetty-maven-plugin[Jetty Maven Plugin] you provi [source, xml, subs="{sub-order}"] ---- - ...