Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #579 from WalkerWatch/jetty-9.3.x 

Updated Chapter 4 with ventilated prose and updated grammar/formatting.
This commit is contained in:
Jesse McConnell 2016-05-19 07:33:35 -05:00
parent ff1bfa599f d828100e2e
commit 8e5ea7abde
11 changed files with 293 additions and 637 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
jetty-documentation/src/main/asciidoc/configuring/deploying/anatomy-of-a-webapp.adoc
View File

@ -17,37 +17,25 @@
[[anatomy-of-a-webapp]]
=== Anatomy of a Web Application
The standard Jetty distribution is capable of deploying standard Servlet
Spec Web Applications, and Jetty internal ContextHandler deployment
descriptors, or even a mix of the two.
The standard Jetty distribution is capable of deploying standard Servlet Spec Web Applications and Jetty internal ContextHandler deployment descriptors, or even a mix of the two.
Web Applications are deployable collections of dynamic (servlets,
filters, jsps, etc..) and static content, support libraries, and
descriptive metadata that are bound to a specific context path on Jetty.
Web Applications are deployable collections of dynamic (servlets, filters, jsps, etc..) and static content, support libraries, and descriptive metadata that are bound to a specific context path on Jetty.
Ultimately the format and layout are defined by the Servlet Spec, and
you should consult the official Servlet Spec documentation for a more
detailed understanding of Web Application layout and structure, however
this will outline basics about how Jetty views these requirements.
Ultimately the format and layout are defined by the Servlet Spec, and the official Servlet Spec documentation should be consulted for a more detailed understanding of Web Application layout and structure; however, this will outline basics about how Jetty views these requirements.
Web Applications can be bundled into a single Web Archive (WAR file) or
as a directory tree.
Web Applications can be bundled into a single Web Archive (WAR file) or as a directory tree.
`/WEB-INF/`::
Special Servlet API defined directory used to store anything related
to the Web Application that are not part of the public access of the
Web Application.
+
If you have content that is accessed by your Web Application
internally, but that should also never be accessed directly by a web
browser, this is the directory you would place them in.
Special Servlet API defined directory used to store anything related to the Web Application that are not part of the public access of the Web Application.
If there is content that is accessed by a Web Application internally, but that should also never be accessed directly by a web browser, this is the directory it would placed in.
`/WEB-INF/web.xml`::
*Required* deployment descriptor defining various behavior of your Web
Application.
*Required* deployment descriptor defining various behavior of the Web Application.
`/WEB-INF/classes/`::
Location for Web Application specific compiled java classes
`/WEB-INF/lib/`::
Directory for JAR files (libraries)
The Jetty internal WebAppClassloader will load classes from
`/WEB-INF/classes/` first, then from jar files found in `/WEB-INF/lib/`.
The Jetty internal `WebAppClassloader` will load classes from `/WEB-INF/classes/` first, then from jar files found in `/WEB-INF/lib/`.

14
jetty-documentation/src/main/asciidoc/configuring/deploying/automatic-webapp-deployment.adoc
View File

@ -17,16 +17,11 @@
[[automatic-webapp-deployment]]
=== Automatic Web Application Deployment
The most basic technique for deploying Web Applications is to simply put
your WAR file or Exploded WAR directory into the
`${jetty.home}/webapps/` directory and let Jetty's deployment scanner
find it and deploy it under a Context path of the same name.
The most basic technique for deploying Web Applications is to put a WAR file or Exploded WAR directory into the `${jetty.home}/webapps/` directory and let Jetty's deployment scanner find it and deploy it under a Context path of the same name.
Only Web Applications that follow the Web Application Layout will be
detected by Jetty and deployed this way.
Only Web Applications that follow the Web Application Layout will be detected by Jetty and deployed this way.
The Context Path assigned to this automatic deployment is based the
filename (or directory name) of your WAR.
The Context Path assigned to this automatic deployment is based the filename (or directory name) of the WAR.
[cols=",",options="header",]
|=======================================================================
@ -35,8 +30,7 @@ filename (or directory name) of your WAR.
|`/webapps/baggywrinkle-1.0.war` |http://host/baggywrinkle-1.0/
|`/webapps/lazaret-2.1.3-SNAPSHOT.war`
|http://host/lazaret-2.1.3-SNAPSHOT/
|`/webapps/lazaret-2.1.3-SNAPSHOT.war` |http://host/lazaret-2.1.3-SNAPSHOT/
|`/webapps/belaying-pins/WEB-INF/web.xml` |http://host/belaying-pins/

3
jetty-documentation/src/main/asciidoc/configuring/deploying/chapter.adoc
View File

@ -19,8 +19,7 @@
This chapter discusses various ways to deploy applications with Jetty.
Topics range from deployment bindings to deploying third party products.
It also includes information about the Deployment Manager, WebApp
Provider, and Overlay Deployer.
It also includes information about the Deployment Manager, WebApp Provider, and Overlay Deployer.
include::anatomy-of-a-webapp.adoc[]
include::automatic-webapp-deployment.adoc[]

91
jetty-documentation/src/main/asciidoc/configuring/deploying/configuring-specific-webapp-deployment.adoc
View File

@ -17,41 +17,29 @@
[[configuring-specific-webapp-deployment]]
=== Configuring a Specific Web Application Deployment
Using the Automatic Web Application Deployment model is quick and easy,
but sometimes you might need to tune certain deployment properties (for
example, you want to deploy with a context path that is not based on the
file name, or you want to define a special database connection pool just
for this web application). You can use a
xref:deployable-descriptor-file[] to accomplish such
tuning.
Using the Automatic Web Application Deployment model is quick and easy, but sometimes you might need to tune certain deployment properties (for example, you want to deploy with a context path that is not based on the file name, or you want to define a special database connection pool just for this web application).
You can use a xref:deployable-descriptor-file[] to accomplish such tuning.
[[deployable-descriptor-file]]
==== Jetty Deployable Descriptor XML File
Jetty supports deploying Web Applications via XML files which will build
an instance of a
link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler]
that Jetty can then deploy.
Jetty supports deploying Web Applications via XML files which will build an instance of a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler] that Jetty can then deploy.
[[using-basic-descriptor-files]]
==== Using Basic Descriptor Files
In a default Jetty installation, Jetty scans its `$JETTY_HOME/webapps`
directory for context deployment descriptor files. To deploy a web
application using such a file, simply place the file in that directory.
In a default Jetty installation, Jetty scans its `$JETTY_HOME/webapps` directory for context deployment descriptor files.
To deploy a web application using such a file, simply place the file in that directory.
The deployment descriptor file itself is an xml file that configures a
link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`]
class. For a basic installation you probably need to set only two
properties:
The deployment descriptor file itself is an xml file that configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`] class.
For a basic installation only two properties need configured:
war::
the filesystem path to the web application file (or directory)
The filesystem path to the web application file (or directory)
contextPath::
the context path to use for the web application
The context path to use for the web application
For example, here is a descriptor file that deploys the file
`/opt/myapp/myapp.war` to the context path `/wiki`:
For example, here is a descriptor file that deploys the file `/opt/myapp/myapp.war` to the context path `/wiki`:
[source,xml]
----
@ -66,8 +54,8 @@ For example, here is a descriptor file that deploys the file
____
[NOTE]
You can use the `SystemProperty` and `Property` elements in your descriptor file.
For example, if you set the system property `myapp.home=/opt/myapp`, you can rewrite the previous example as:
Both `SystemProperty` and `Property` elements can be used in the descriptor file.
For example, if the system property is set tp `myapp.home=/opt/myapp`, the previous example can be rewritten as:
____
[source,xml]
@ -81,23 +69,17 @@ ____
</Configure>
----
If you need to change the home path for your application, you can simply
change the system property. This is useful if you frequently switch
among multiple versions of an app.
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.
[[configuring-advanced-descriptor-files]]
==== Configuring Advanced Descriptor Files
If you look at the documentation for the
link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`]
class, you notice that there are a lot more properties than just the two
mentioned above. Here are some examples that configure advanced options
with your descriptor file.
Official documentation for the for the link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`] class lists all the properties that can be set.
Here are some examples that configure advanced options in the descriptor file.
This first example tells Jetty not to expand the WAR file when deploying
it. This can help make it clear that people should not be making changes
to the temporary unpacked WAR because such changes do not persist, and
therefore do not apply the next time the web application deploys.
This first example tells Jetty not to expand the WAR file when deploying it.
This can help make it clear that users should not make changes to the temporary unpacked WAR because such changes do not persist, and therefore do not apply the next time the web application deploys.
[source,xml]
----
@ -111,13 +93,9 @@ therefore do not apply the next time the web application deploys.
</Configure>
----
The next example retrieves the JavaEE Servlet context and sets an
initialization parameter on it. You can also use the `setAttribute`
method to set a Servlet context attribute. However, since the ` web.xml`
for the web application is processed after the deployment descriptor,
the `
web.xml` values overwrite identically named attributes from the
deployment descriptor.
The next example retrieves the JavaEE Servlet context and sets an initialization parameter on it.
The `setAttribute` method can also be used to set a Servlet context attribute.
However, since the `web.xml` for the web application is processed after the deployment descriptor, the `web.xml` values overwrite identically named attributes from the deployment descriptor.
[source,xml]
----
@ -136,11 +114,9 @@ deployment descriptor.
</Configure>
----
The following example sets a special `web.xml` override descriptor. This
descriptor is processed after the web application's `web.xml`, so it may
override identically named attributes. This feature is useful if you
want to add parameters or additional Servlet mappings without breaking
open a packed WAR file.
The following example sets a special `web.xml` override descriptor.
This descriptor is processed after the web application's `web.xml`, so it may override identically named attributes.
This feature is useful when adding parameters or additional Servlet mappings without breaking open a packed WAR file.
[source,xml]
----
@ -154,11 +130,8 @@ open a packed WAR file.
</Configure>
----
The next example configures not only the web application context, but
also a database connection pool (see xref:jndi-datasource-examples[]
that our application can then use. If the ` web.xml` does not include a
reference to this data source, you can use the override descriptor
mechanism (the previous example), to include it.
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]
----
@ -184,12 +157,6 @@ mechanism (the previous example), to include it.
</Configure>
----
There are many other settings that you can change on a
link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`].
The link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[javadoc]
for WebAppContext is a good source of information. Also see the
documentation on link:#troubleshooting-zip-exceptions[avoiding zip file
exceptions] for a description of WebAppContext settings that determine
such things as whether or not the war is automatically unpacked during
deployment, or whether certain sections of a webapp are copied to a
temporary location.
There are many other settings that can be changed in a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`].
The link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[javadoc] for `WebAppContext` is a good source of information.
Also see the documentation on link:#troubleshooting-zip-exceptions[avoiding zip file exceptions] for a description of `WebAppContext` settings that determine such things as whether or not the war is automatically unpacked during deployment, or whether certain sections of a webapp are copied to a temporary location.

161
jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-architecture.adoc
View File

@ -17,105 +17,67 @@
[[deployment-architecture]]
=== Deployment Architecture
Jetty is built around an extensible Deployment Manager architecture
complete with formal LifeCycle for Web Applications going through it.
Jetty is built around an extensible Deployment Manager architecture complete with formal LifeCycle for Web Applications going through it.
For Jetty to serve content (static or dynamic), you need to create a
link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler]
and add it to Jetty in the appropriate place. A pluggable
DeploymentManager exists in Jetty 7 and later to make this process
easier. The Jetty distribution contains example DeploymentManager
configurations to deploy WAR files found in a directory to Jetty, and to
deploy Jetty `context.xml` files into Jetty as well.
For Jetty to serve content (static or dynamic), a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler] needs to be configured and added to Jetty in the appropriate location.
A pluggable `DeploymentManager` exists in Jetty 7 and later to make this process easier.
The Jetty distribution contains example `DeploymentManager` configurations to deploy WAR files found in a directory to Jetty, and to deploy Jetty `context.xml` files into Jetty as well.
The DeploymentManager is the heart of the typical webapp deployment
mechanism; it operates as a combination of an Application LifeCycle
Graph, Application Providers that find and provide Applications into the
Application LifeCycle Graph, and a set of bindings in the graph that
control the deployment process.
The `DeploymentManager` is the heart of the typical webapp deployment mechanism; it operates as a combination of an Application LifeCycle Graph, Application Providers that find and provide Applications into the Application LifeCycle Graph, and a set of bindings in the graph that control the deployment process.
image:images/Jetty_DeployManager_DeploymentManager_Roles.png[image,width=195]
[[udm-application-providers]]
==== Application Providers
Before Jetty deploys an application, an
link:{JDURL}/org/eclipse/jetty/deploy/AppProvider.html[AppProvider]
identifies the App and then provides it to the DeploymentManager. The
main AppProvider with the Jetty distribution is the
link:{JDURL}/org/eclipse/jetty/deploy/providers/WebAppProvider.html[WebAppProvider.]
Before Jetty deploys an application, an link:{JDURL}/org/eclipse/jetty/deploy/AppProvider.html[AppProvider] identifies the App and then provides it to the `DeploymentManager`.
The main `AppProvider` with the Jetty distribution is the link:{JDURL}/org/eclipse/jetty/deploy/providers/WebAppProvider.html[WebAppProvider.]
[[udm-application-lifecycle-graph]]
==== Application LifeCycle Graph
The core feature of the DeploymentManager is the
link:{JDURL}/org/eclipse/jetty/deploy/AppLifeCycle.html[Application
LifeCycle Graph].
The core feature of the `DeploymentManager` is the link:{JDURL}/org/eclipse/jetty/deploy/AppLifeCycle.html[Application LifeCycle Graph].
image:images/Jetty_DeployManager_AppLifeCycle-1.png[image,width=340]
The nodes and edges of this graph are pre-defined in Jetty along the
most common actions and states found. These nodes and edges are not
hardcoded; you can adjust and add to them depending on your needs (for
example, any complex requirements for added workflow, approvals,
staging, distribution, coordinated deploys for a cluster or cloud,
etc.).
The nodes and edges of this graph are pre-defined in Jetty along the most common actions and states found.
These nodes and edges are not hardcoded; they can be adjusted and added to depending on need (for example, any complex requirements for added workflow, approvals, staging, distribution, coordinated deploys for a cluster or cloud, etc.).
New applications enter this graph at the Undeployed node, and the
link:{JDURL}/org/eclipse/jetty/deploy/DeploymentManager.html#requestAppGoal(org.eclipse.jetty.deploy.App[`java.lang.String DeploymentManager.requestAppGoal(App,String)`]
method pushes them through the graph.
New applications enter this graph at the Undeployed node, and the link:{JDURL}/org/eclipse/jetty/deploy/DeploymentManager.html#requestAppGoal(org.eclipse.jetty.deploy.App[`java.lang.String DeploymentManager.requestAppGoal(App,String)`] method pushes them through the graph.
[[udm-lifecycle-bindings]]
==== LifeCycle Bindings
A set of default
link:{JDURL}/org/eclipse/jetty/deploy/AppLifeCycle.Binding.html[`AppLifeCycle.Bindings`]
defines standard behavior, and handles deploying, starting, stopping,
and undeploying applications. If you choose, you can write your own
`AppLifeCycle.Bindings` and assign them to anywhere on the Application
LifeCycle graph.
A set of default link:{JDURL}/org/eclipse/jetty/deploy/AppLifeCycle.Binding.html[`AppLifeCycle.Bindings`] defines standard behavior, and handles deploying, starting, stopping, and undeploying applications.
If desired, custom `AppLifeCycle.Bindings` can be written and assigned anywhere on the Application LifeCycle graph.
Examples of new `AppLifeCycle.Binding` implementations that you can
write include:
Examples of new `AppLifeCycle.Binding` implementations that can be developed include:
* Validating the incoming application.
* Preventing the deployment of known forbidden applications.
* Submitting the installation to an application auditing service in a
corporate environment.
* Submitting the installation to an application auditing service in a corporate environment.
* Distributing the application to other nodes in the cluster or cloud.
* Emailing owner/admin of change of state of the application.
There are four default bindings:
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardDeployer.html[StandardDeployer]
— Deploys the ContextHandler into Jetty in the appropriate place.
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardStarter.html[StandardStarter]
— Sets the ContextHandler to started and start accepting incoming
requests.
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardStopper.html[StandardStopper]
— Stops the ContextHandler and stops accepting incoming requests.
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardUndeployer.html[StandardUndeployer]
— Removes the ContextHandler from Jetty.
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardDeployer.html[StandardDeployer] — Deploys the ContextHandler into Jetty in the appropriate place.
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardStarter.html[StandardStarter] — Sets the ContextHandler to started and start accepting incoming requests.
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardStopper.html[StandardStopper] — Stops the ContextHandler and stops accepting incoming requests.
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardUndeployer.html[StandardUndeployer] — Removes the ContextHandler from Jetty.
image:images/Jetty_DeployManager_DefaultAppLifeCycleBindings.png[image,width=851]
A fifth, non-standard binding, called
link:{JDURL}/org/eclipse/jetty/deploy/bindings/DebugBinding.html[Debug
Binding], is also available for debugging reasons; It logs the various
transitions through the Application LifeCycle.
A fifth, non-standard binding, called link:{JDURL}/org/eclipse/jetty/deploy/bindings/DebugBinding.html[DebugBinding], is also available for debugging reasons; it logs the various transitions through the Application LifeCycle.
[[default-web-app-provider]]
==== Understanding the Default WebAppProvider
The
link:{JDURL}/org/eclipse/jetty/deploy/providers/WebAppProvider.html[WebAppProvider]
is for the deployment of Web Applications packaged as WAR files,
expanded as a directory, or declared in a
xref:deployable-descriptor-file[]. It supports hot (re)deployment.
The link:{JDURL}/org/eclipse/jetty/deploy/providers/WebAppProvider.html[WebAppProvider] is used for the deployment of Web Applications packaged as WAR files, expanded as a directory, or declared in a xref:deployable-descriptor-file[].
It supports hot (re)deployment.
The basic operation of the WebAppProvider is to periodically scan a
directory for deployables. In the standard Jetty Distribution, this is
configured in the `${jetty.home}/etc/jetty-deploy.xml` file.
The basic operation of the `WebAppProvider` is to periodically scan a directory for deployables.
In the standard Jetty Distribution, this is configured in the `${jetty.home}/etc/jetty-deploy.xml` file.
[source,xml]
----
@ -145,62 +107,43 @@ configured in the `${jetty.home}/etc/jetty-deploy.xml` file.
</Configure>
----
The above configuration will create a DeploymentManager tracked as a
Server LifeCycle Bean, with the following configuration.
The above configuration will create a `DeploymentManager` tracked as a Server LifeCycle Bean, with the following configuration.
contexts::
A passed in reference to the HandlerContainer into which the
discovered webapps are deployed. This is normally a reference that
points to the `id="Contexts"` found in the
`${jetty.home}/etc/jetty.xml` file, which itself is an instance of
ContextHandlerCollection.
A passed in reference to the HandlerContainer into which the discovered webapps are deployed.
This is normally a reference that points to the `id="Contexts"` found in the `${jetty.home}/etc/jetty.xml` file, which itself is an instance of `ContextHandlerCollection`.
monitoredDirName::
Is a file path or URL to the directory to scan for web applications.
The file path or URL to the directory to scan for web applications.
+
Scanning follows these rules:
+
1. Base directory must exist
2. Hidden Files (starting with `"."`) are ignored
1. A base directory must exist.
2. Hidden Files (starting with `"."`) are ignored.
3. Directories with names ending in `".d"` are ignored.
4. Common CVS directories `"CVS"` and `"CVSROOT"` are ignored
5. Any `*.war` files are considered
link:#automatic-webapp-deployment[automatic deployables]
6. Any `*.xml` files are considered
link:#deployable-descriptor-file[context descriptor deployables]
7. In the special case where both a WAR file and XML file exists for
same base name the XML file is assumed to configure and reference the
WAR file (see xref:configuring-specific-webapp-deployment[]).
Since jetty-9.2.7, if either the WAR file or its corresponding XML
file changes, the webapp will be redeployed.
8. A directory is considered to be deployable
9. In the special case where both a Directory and WAR file of the
same name exists the WAR file is assumed to be an automatic
deployable.
10. In the special case where both a DIrectory and XML file of the
same name exists the XML file is assumed to configure and reference
the Directory.
4. Common CVS directories `"CVS"` and `"CVSROOT"` are ignored.
5. Any `*.war` files are considered link:#automatic-webapp-deployment[automatic deployables].
6. Any `*.xml` files are considered link:#deployable-descriptor-file[context descriptor deployables].
7. In the special case where both a WAR file and XML file exists for same base name, the XML file is assumed to configure and reference the WAR file (see xref:configuring-specific-webapp-deployment[]).
Since jetty-9.2.7, if either the WAR file or its corresponding XML file changes, the webapp will be redeployed.
8. A directory is considered to be deployable.
9. In the special case where both a Directory and WAR file of the same name exists, the WAR file is assumed to be an automatic deployable.
10. In the special case where both a Directory and XML file of the same name exists, the XML file is assumed to configure and reference the Directory.
11. All other directories are subject to automatic deployment.
12. If automatic deployment is used, and the special filename
`root.war/ROOT.war` or directory name `root/ROOT` will result in a
deployment to the `"/"` context path.
12. If automatic deployment is used, and the special filename `root.war/ROOT.war` or directory name `root/ROOT` will result in a deployment to the `"/"` context path.
defaultsDescriptor::
Specifies the default Servlet web descriptor to use for all Web
Applications. The intent of this descriptor is to include common
configuration for the Web Application before the Web Application's own
`/WEB-INF/web.xml` is applied. The `${jetty.home}/etc/webdefault.xml`
that comes with the Jetty distribution controls the configuration of
the JSP and Default servlets, along with mimetypes and other basic
metadata.
Specifies the default Servlet web descriptor to use for all Web Applications.
The intent of this descriptor is to include common configuration for the Web Application before the Web Application's own `/WEB-INF/web.xml` is applied.
The `${jetty.home}/etc/webdefault.xml` that comes with the Jetty distribution controls the configuration of the JSP and Default servlets, along with MIME-types and other basic metadata.
scanInterval::
Is the period in seconds between sweeps of the `monitoredDirName` for
changes: new contexts to deploy, changed contexts to redeploy, or
removed contexts to undeploy.
The period in seconds between sweeps of the `monitoredDirName` for changes: new contexts to deploy, changed contexts to redeploy, or removed contexts to undeploy.
extractWars::
If parameter is true, any packed WAR or zip files are first extracted
to a temporary directory before being deployed. This is advisable if
there are uncompiled JSPs in the web apps.
If parameter is true, any packed WAR or zip files are first extracted to a temporary directory before being deployed.
This is advisable if there are uncompiled JSPs in the web apps.
parentLoaderPriority::
parameter is a boolean that selects whether the standard Java
link:#jetty-classloading[parent first delegation] is used or the
link:#jetty-classloading[servlet specification webapp classloading
priority]. The latter is the default.
Parameter is a boolean that selects whether the standard Java link:#jetty-classloading[parent first delegation] is used or the link:#jetty-classloading[servlet specification webapp classloading priority].
The latter is the default.

196
jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-processing-webapps.adoc
View File

@ -17,32 +17,18 @@
[[configuring-webapps]]
=== Deployment Processing of WebAppContexts
Web applications require a certain amount of processing before they can
go into service: they may need to be unpacked, a special classloader
created for their jars, web.xml and web-fragment.xml descriptors
processed, and classes scanned for annotations amongst many other
things. As web applications have become more complex, we have added ways
to help you customize by either broadening or lessening the amount of
processing that is done at deployment time. In this section we will look
at this processing, and how you can tailor it.
Web applications require a certain amount of processing before they can go into service: they may need to be unpacked, a special classloader created for their jar files, web.xml and web-fragment.xml descriptors processed, and classes scanned for annotations amongst many other things.
As web applications have become more complex, Jetty gas added ways to assist with customization by either broadening or lessening the amount of processing that is done at deployment time.
This section will examine this processing and it can be tailored to fit individual needs.
If instead you're looking for information on how to configure a specific
WebAppContext - such as its context path, whether it should be unpacked
or not - then you can find that in the section entitled
link:#configuring-specific-webapp-deployment[Configuring a Specific
WebApp Deployment].
If instead you're looking for information on how to configure a specific WebAppContext - such as its context path, whether it should be unpacked or not - then you can find that in the section entitled link:#configuring-specific-webapp-deployment[Configuring a Specific WebApp Deployment].
[[webapp-configurations]]
==== Configuration Classes
As a webapp is being deployed, a series of
link:{JDURL}/org/eclipse/jetty/webapp/Configuration.html[org.eclipse.jetty.webapp.Configuration]
classes are applied to it, each one performing a specific function. The
ordering of these Configurations is significant as subsequent
Configurations tend to build on information extracted or setup in
foregoing Configurations. These are the default list, in order, of
Configurations that are applied to each
link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[org.eclipse.jetty.webapp.WebAppContex]t:
As a webapp is being deployed, a series of link:{JDURL}/org/eclipse/jetty/webapp/Configuration.html[org.eclipse.jetty.webapp.Configuration] classes are applied to it, each one performing a specific function.
The ordering of these Configurations is significant as subsequent Configurations tend to build on information extracted or setup in foregoing Configurations.
These are the default list, in order, of Configurations that are applied to each link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[org.eclipse.jetty.webapp.WebAppContex]t:
.Default Configuration classes
[cols=",",]
@ -66,89 +52,62 @@ META-INF/web-fragment.xml
===== Anatomy of a Configuration Class
A Configuration class is called 5 times in different phases of the
WebAppContext's lifecycle:
A Configuration class is called 5 times in different phases of the WebAppContext's lifecycle:
preConfigure::
As the WebAppContext is starting up this phase is executed. The
Configuration should discover any of the resources it will need during
the subsequent phases.
As the WebAppContext is starting up this phase is executed.
The Configuration should discover any of the resources it will need during the subsequent phases.
configure::
This phase is where the work of the class is done, usually using the
resources discovered during the preConfigure phase.
This phase is where the work of the class is done, usually using the resources discovered during the preConfigure phase.
postConfigure::
This phase allows the Configuration to clear down any resources that
may have been created during the previous 2 phases that are not needed
for the lifetime of the WebAppContext.
This phase allows the Configuration to clear down any resources that may have been created during the previous 2 phases that are not needed for the lifetime of the `WebAppContext`.
deconfigure::
This phase occurs whenever a WebAppContext is being stopped and allows
the Configuration to undo any resources/metadata that it created. A
WebAppContext should be able to be cleanly start/stopped multiple
times without resources being held.
This phase occurs whenever a `WebAppContext` is being stopped and allows the Configuration to undo any resources/metadata that it created.
A `WebAppContext` should be able to be cleanly start/stopped multiple times without resources being held.
destroy::
This phase is called when a WebAppContext is actually removed from
service. For example, the war file associated with it is deleted from
the $JETTY_HOME/webapps directory.
This phase is called when a `WebAppContext` is actually removed from service.
For example, the war file associated with it is deleted from the $JETTY_HOME/webapps directory.
Each phase is called on each Configuration class in the order in which
the Configuration class is listed. So for example, using our default
Configuration classes as an example, preConfigure() will be called on
WebInfConfiguration, WebXmlConfiguration, MetaInfConfiguration,
FragmentConfiguration and then JettyWebXmlConfiguration. The cycle
begins again for the configure() phase and again for the postConfigure()
phases. The cycle is repeated _in reverse order_ for the deconfigure()
and eventually the destroy() phases.
Each phase is called on each Configuration class in the order in which the `Configuration` class is listed.
Using the default Configuration classes as an example, preConfigure() will be called on `WebInfConfiguration`, `WebXmlConfiguration`, `MetaInfConfiguration`, `FragmentConfiguration` and then `JettyWebXmlConfiguration`.
The cycle begins again for the `configure()` phase and again for the `postConfigure()` phases.
The cycle is repeated _in reverse order_ for the `deconfigure()` and eventually the `destroy()` phases.
===== Extending Container Support by Creating Extra Configurations
As we have seen, there is a default set of Configurations that support
basic deployment of a webapp. You will notice that we have not mentioned
JavaEE features such as JNDI, nor advanced servlet spec features such as
annotations. That is because Jetty's philosophy is to allow the user to
tailor the container exactly to his needs. If you do not need these kind
of features, then you do not pay the price of them - an important
consideration because features such as annotations require extensive and
time-consuming scanning of WEB-INF/lib jars. As modern webapps may have
scores of these jars, it can be a source of significant deployment
delay. We will see in the section link:#webapp-context-attributes[Other
Configuration] another helpful webapp facility that Jetty provides for
cutting down the time spent analysing jars.
As shows, there is a default set of Configurations that support basic deployment of a webapp.
JavaEE features such as JNDI, nor advanced servlet spec features such as annotations have not been mentioned.
That is because Jetty's philosophy is to allow the user to tailor the container exactly to their needs.
If these features are not needed, then Jetty does not pay the price for them - an important consideration because features such as annotations require extensive and time-consuming scanning of `WEB-INF/lib` jars.
As modern webapps may have scores of these jars, it can be a source of significant deployment delay.
We will see in the section link:#webapp-context-attributes[Other Configuration] another helpful webapp facility that Jetty provides for cutting down the time spent analyzing jars.
Jetty makes use of the flexibility of Configurations to make JNDI and
annotation support pluggable.
Jetty makes use of the flexibility of Configurations to make JNDI and annotation support pluggable.
Firstly, lets look at how Configurations help enable JNDI.
[[jndi-configuration-classes]]
====== Example: JNDI Configurations
JNDI lookups within web applications require the container to hookup
resources defined in the container's environment to that of the web
application. To acheive that, we use 2 extra Configurations:
JNDI lookups within web applications require the container to hookup resources defined in the container's environment to that of the web application.
To achieve that, we use 2 extra Configurations:
.JNDI Configuration classes
[cols=",",]
|=======================================================================
|link:{JDURL}/org/eclipse/jetty/plus/webapp/EnvConfiguration.html[org.eclipse.jetty.plus.webapp.EnvConfiguration]
|Creates java:comp/env for the webapp, applies a WEB-INF/jetty-env.xml
file
|Creates java:comp/env for the webapp, applies a WEB-INF/jetty-env.xml file
|link:{JDURL}/org/eclipse/jetty/plus/webapp/PlusConfiguration.html[org.eclipse.jetty.plus.webapp.PlusConfiguration]
|Processes JNDI related aspects of WEB-INF/web.xml and hooks up naming
entries
|Processes JNDI related aspects of WEB-INF/web.xml and hooks up naming entries
|=======================================================================
These configurations must be added in _exactly_ the order shown above
and should be inserted _immediately before_ the
link:{JDURL}/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html[org.eclipse.jetty.webapp.JettyWebXmlConfiguration]
class in the list of configurations. To fully support JNDI, you need to
do a couple of other things, full details of which you can find
link:#jndi[here].
These configurations must be added in _exactly_ the order shown above and should be inserted _immediately before_ the link:{JDURL}/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html[org.eclipse.jetty.webapp.JettyWebXmlConfiguration] class in the list of configurations.
To fully support JNDI, you need to do a couple of other things, full details of which can be found link:#jndi[here].
====== Example: Annotation Configurations
We need just one extra Configuration class to help provide servlet
annotation scanning:
We need just one extra Configuration class to help provide servlet annotation scanning:
.Annotation Configuration classes
[cols=",",]
@ -158,23 +117,18 @@ annotation scanning:
@WebListener etc
|=======================================================================
The above configuration class must be _inserted immediately before_ the
link:{JDURL}/org/eclipse/jetty/webapp/JettWebXmlConfiguration.html[org.eclipse.jetty.webapp.JettyWebXmlConfiguration]
class in the list of configurations. To fully support annotations, you
need to do a couple of other things, details of which can be found here.
The above configuration class must be _inserted immediately before_ the link:{JDURL}/org/eclipse/jetty/webapp/JettWebXmlConfiguration.html[org.eclipse.jetty.webapp.JettyWebXmlConfiguration] class in the list of configurations.
To fully support annotations, you need to do a couple of other things, details of which can be found below.
===== How to Set the List of Configurations
You have a number of options for how to make Jetty use a different list
of Configurations.
You have a number of options for how to make Jetty use a different list of Configurations.
====== Setting the list directly on the WebAppContext
If you have only one webapp that you wish to affect, this may be the
easiest option. You will, however, either need to have a context xml
file that represents your web app, or you need to call the equivalent in
code. Let's see an example of how we would add in the Configurations for
both JNDI _and_ annotations:
If you have only one webapp that you wish to affect, this may be the easiest option.
You will, however, either need to have a context xml file that represents your web app, or you need to call the equivalent in code.
Let's see an example of how we would add in the Configurations for both JNDI _and_ annotations:
[source,xml]
----
@ -201,15 +155,12 @@ both JNDI _and_ annotations:
</Configure>
----
Of course, you can also use this method to reduce the Configurations
applied to a specific WebAppContext.
Of course, you can also use this method to reduce the Configurations applied to a specific `WebAppContext`.
====== Setting the list for all webapps via the Deployer
If you use the link:#deployment-architecture[deployer], you can set up
the list of Configuration classes on the
link:#default-web-app-provider[WebAppProvider]. They will then be
applied to each WebAppContext deployed by the deployer:
If you use the link:#deployment-architecture[deployer], you can set up the list of Configuration classes on the link:#default-web-app-provider[WebAppProvider].
They will then be applied to each `WebAppContext` deployed by the deployer:
[source,xml]
----
@ -251,13 +202,9 @@ applied to each WebAppContext deployed by the deployer:
====== Adding or inserting to an existing list
Instead of having to enumerate the list in its entirety, you can simply
nominate classes that you want to add, and indicate whereabouts in the
list you want them inserted. Let's look at an example of using this
method to add in Configuration support for JNDI - as usual you can
either do this in an xml file, or via equivalent code. This example uses
an xml file, in fact it is the $JETTY_HOME/etc/jetty-plus.xml file from
the Jetty distribution:
Instead of having to enumerate the list in its entirety, you can simply nominate classes that you want to add, and indicate whereabouts in the list you want them inserted.
Let's look at an example of using this method to add in Configuration support for JNDI - as usual you can either do this in an xml file, or via equivalent code.
This example uses an xml file, in fact it is the $JETTY_HOME/etc/jetty-plus.xml file from the Jetty distribution:
[source,xml]
----
@ -285,16 +232,12 @@ the Jetty distribution:
</Configure>
----
The
link:{JDURL}/org/eclipse/jetty/webapp/Configuration.html[org.eclipse.jetty.webapp.Configuration.ClassList]
class provides these methods for insertion:
The link:{JDURL}/org/eclipse/jetty/webapp/Configuration.html[org.eclipse.jetty.webapp.Configuration.ClassList] class provides these methods for insertion:
addAfter::
inserts the supplied list of Configuration class names after the given
Configuration class name
Inserts the supplied list of Configuration class names after the given Configuration class name.
addBefore::
inserts the supplied list of Configuration class names before the
given Configuration class name
Inserts the supplied list of Configuration class names before the given Configuration class name.
[[webapp-context-attributes]]
==== Other Configuration
@ -302,24 +245,16 @@ addBefore::
[[container-include-jar-pattern]]
===== org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern
This is a link:#context_attributes[context attribute] that can be set
onlink:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[an
org.eclipse.jetty.webapp.WebAppContext] to control which parts of the
_container's_ classpath should be processed for things like annotations,
META-INF/resources, META-INF/web-fragment.xml and tlds inside META-INF.
This is a link:#context_attributes[context attribute] that can be set on link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[an org.eclipse.jetty.webapp.WebAppContext] to control which parts of the _container's_ classpath should be processed for things like annotations, `META-INF/resources`, `META-INF/web-fragment.xml` and `tlds` inside `META-INF`.
Normally, nothing from the container classpath will be included for
processing. However, sometimes you will need to include some. For
example, you may have some libraries that are shared amongst your
webapps and thus you have put them into a $JETTY_HOME/lib directory. The
libraries contain annotations and therefore must be scanned.
Normally, nothing from the container classpath will be included for processing.
However, sometimes you will need to include some.
For example, you may have some libraries that are shared amongst your webapps and thus you have put them into a `$JETTY_HOME/lib` directory.
The libraries contain annotations and therefore must be scanned.
The value of this attribute is a regexp that defines which__jars__ and
_class directories_ from the container's classpath should be examined.
The value of this attribute is a regexp that defines which _jars_ and _class directories_ from the container's classpath should be examined.
Here's an example from a context xml file (although as always, you could
have accomplished the same in code), which would match any jar whose
name starts with "foo-" or "bar-", or a directory named "classes":
Here's an example from a context xml file (although as always, you could have accomplished the same in code), which would match any jar whose name starts with "foo-" or "bar-", or a directory named "classes":
[source,xml]
----
@ -336,22 +271,16 @@ name starts with "foo-" or "bar-", or a directory named "classes":
</Configure>
----
Note that the order of the patterns defines the ordering of the scanning
of the jars or class directories.
Note that the order of the patterns defines the ordering of the scanning of the jars or class directories.
[[web-inf-include-jar-pattern]]
===== org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern
Similarly to the previous link:#context_attributes[context attribute],
this attribute controls which jars are processed for things like
annotations, META-INF/resources, META-INF/web-fragment.xml and tlds in
META-INF. However, this attribute controls which jars from the
_webapp's_ classpath (usually WEB-INF/lib) are processed. This can be
particularly useful when you have dozens of jars in WEB-INF/lib, but you
know that only a few need to be scanned.
Similarly to the previous link:#context_attributes[context attribute], this attribute controls which jars are processed for things like annotations, `META-INF/resources`, `META-INF/web-fragment.xml` and `tlds` in `META-INF`.
However, this attribute controls which jars from the _webapp's_ classpath (usually `WEB-INF/lib`) are processed.
This can be particularly useful when you have dozens of jars in `WEB-INF/lib`, but you know that only a few need to be scanned.
Here's an example (in an xml file, but you can do the same in code) of a
pattern that matches any jar that starts with "spring-":
Here's an example in a xml file of a pattern that matches any jar that starts with "spring-":
[source,xml]
----
@ -368,5 +297,4 @@ pattern that matches any jar that starts with "spring-":
</Configure>
----
Note that the order of the patterns defines the ordering of the scanning
of the jars.
Note that the order of the patterns defines the ordering of the scanning of jar files.

26
jetty-documentation/src/main/asciidoc/configuring/deploying/hot-deployment.adoc
View File

@ -17,27 +17,20 @@
[[hot-deployment]]
=== Hot Deployment
Jetty lets you deploy an arbitrary context or web application by
monitoring a directory for changes. If you add a web application or a
context descriptor to the directory, Jetty's DeploymentManager (DM)
deploys a new context. If you touch or update a context descriptor, the
DM stops, reconfigures, and redeploys its context. If you remove a
context, the DM stops it and removes it from the server.
Jetty allows for deploying an arbitrary context or web application by monitoring a directory for changes.
If a web application or a context descriptor is added to the directory, Jetty's DeploymentManager (DM) deploys a new context.
If a context descriptor is touched or updated, the DM stops, reconfigures, and redeploys its context.
If a context is removed, the DM stops it and removes it from the server.
To control this behavior, you'll want to configure some WebAppProvider
properties.
This behavior can be controlled by configuring `WebAppProvider` properties.
monitoredDirName::
The directory to scan for possible deployable Web Applications (or
Deployment Descriptor XML files)
The directory to scan for possible deployable Web Applications (or Deployment Descriptor XML files).
scanInterval::
Number of seconds between scans of the provided `monitoredDirName`.
+
A value of `0` disables the continuous hot deployment scan, Web
Applications will be deployed on startup only.
A value of `0` disables the continuous hot deployment scan, Web Applications will be deployed on startup only.
The default location for this configuration is in the
`${jetty.home}/etc/jetty-deploy.xml` file.
The default location for this configuration is in the `${jetty.home}/etc/jetty-deploy.xml` file.
[source,xml]
----
@ -74,5 +67,4 @@ The default location for this configuration is in the
See xref:default-web-app-provider[] for more configuration details.
See also xref:deployment-architecture[] for detailed conceptual
information.
See also xref:deployment-architecture[] for detailed conceptual information.

259
jetty-documentation/src/main/asciidoc/configuring/deploying/overlay-deployer.adoc
View File

@ -22,114 +22,75 @@ ____
This feature is reintroduced in Jetty 9.0.4
____
The Jetty Overlay Deployer allows you to overlay multiple WAR files so
that you can customise, configure, and deploy a web application without
unpacking, modifying and repacking the WAR file. This has the following
benefits:
The Jetty Overlay Deployer allows multiple WAR files to be overlaid so that a web application can be customized, configured, and deployed without unpacking, modifying and repacking the WAR file.
This has the following benefits:
* You can keep the WAR file immutable, even signed, so that it is clear
which version you have deployed.
* All modifications you make to customise/configure the web application
are separate WARs, and thus are easily identifiable for review and
migration to new versions.
* You can create a parameterised template overlay that contains common
customisations and configuration that apply to many instances of the web
application (for example, for multi-tenant deployment).
* Because the layered deployment clearly identifies the common and
instance specific components, Jetty is able to share classloaders and
static resource caches for the template, greatly reducing the memory
footprint of multiple instances.
* WAR files can be kept immutable, even signed, so that it is clear which version is deployed.
* All modifications made to customize/configure the web application are separate WARs, and thus are easily identifiable for review and migration to new versions.
* A parameterized template overlay can be created that contains common customizations and configuration that apply to many instances of the web application (for example, for multi-tenant deployment).
* Because the layered deployment clearly identifies the common and instance specific components, Jetty is able to share classloaders and static resource caches for the template, greatly reducing the memory footprint of multiple instances.
This tutorial describes how to configure Jetty to use the Overlay
deployer, and how to deploy multiple instances of a web application,
using the JTrac application in the example.
This tutorial describes how to configure Jetty to use the Overlay Deployer, and how to deploy multiple instances of a web application using the JTrac application in the example.
[[overlay-overview]]
==== Overview
Customising, configuring and deploying a web application bundled as a
WAR file frequently includes some or all of these steps:
Customizing, configuring and deploying a web application bundled as a WAR file frequently includes some or all of these steps:
* Editing the `WEB-INF/web.xml` file to set init parameters, add
filters/servlets or to configure JNDI resources.
* Editing other application specific configuration files under
`WEB-INF/`.
* Editing container specific configuration files under `WEB-INF/` (for
example, `jetty-web.xml` or `jboss-web.xml`).
* Adding/modifying static content such as images and CSS to create a
style or themes for the web application.
* Adding Jars to the container classpath for Datasource and other
resources.
* Editing the `WEB-INF/web.xml` file to set init parameters, add filters/servlets or to configure JNDI resources.
* Editing other application specific configuration files under `WEB-INF/`.
* Editing container specific configuration files under `WEB-INF/` (for example, `jetty-web.xml` or `jboss-web.xml`).
* Adding/modifying static content such as images and CSS to create a style or themes for the web application.
* Adding Jars to the container classpath for Datasource and other resources.
* Modifying the container configuration to provide JNDI resources.
The result is that the customisations and configurations blend into both
the container and the WAR file. If you upgrade either the container or
the base WAR file to a new version, it can be a very difficult and error
prone task to identify all the changes that you have made, and to
reapply them to a new version.
The result is that the customizations and configurations blend into both the container and the WAR file.
If either the container or the base WAR file is upgraded to a new version, it can be a very difficult and error prone task to identify all the changes that have been made and to reapply them to a new version.
[[overlay-overlays]]
==== Overlays
To solve the problems highlighted above, Jetty 7.4 introduces WAR
overlays (a concept borrowed from the Maven WAR plugin). An overlay is
basically just another WAR file, whose contents merge on top of the
original WAR so that you can add or replace files. Jetty overlays also
allow you to mix in fragments of web.xml, which means you can modify the
configuration without replacing it.
To solve the problems highlighted above, Jetty 7.4 introduces WAR overlays (a concept borrowed from the Maven WAR plugin).
An overlay is basically just another WAR file, whose contents merge on top of the original WAR so that filed can be added or replaced.
Jetty overlays also allow fragments of `web.xml` to be mixed in, which means the configuration can be modified without replacing it.
[[overlay-jtrac]]
==== JTrac Overlay Example
The JTrac issue tracking web application is a good example of a typical
web application, as it uses the usual suspects of libs: spring,
hibernate, dom4j, commons-*, wicket, etc. The files for this
demonstration are available in overlays-demo.tar.gz. You can expand it
on top of the jetty distribution; this tutorial expands it to /tmp and
installs the components step-by-step:
The JTrac issue tracking web application is a good example of a typical web application, as it uses the usual suspects of libs: spring, hibernate, dom4j, commons-*, wicket, etc.
The files for this demonstration are available in overlays-demo.tar.gz.
The demonstation can be expanded on top of the jetty distribution; this tutorial expands it to /tmp and installs the components step-by-step:
[source, screen]
....
----
$ cd /tmp
$ wget http://webtide.intalio.com/wp-content/uploads/2011/05/overlays-demo.tar.gz
$ tar xfvz overlays-demo.tar.gz
$ export OVERLAYS=/tmp/overlays
....
----
[[overlay-configure]]
==== Configuring Jetty for Overlays
Overlays support is included in jetty distributions from 7.4.1-SNAPSHOT
onwards, so you can download a distribution from oss.sonatype.org or
maven central and unpack into a directory. You need to edit the
start.ini file so that it includes the overlay option and configuration
file. The resulting file should look like:
Overlays support is included in jetty distributions from 7.4.1-SNAPSHOT onwards, which can be downloaded from oss.sonatype.org or Maven Central and unpack into a directory.
The `start.ini` file needs edited so that it includes the overlay option and configuration file.
The resulting file should look like:
[source,plain]
----
OPTIONS=Server,jsp,jmx,resources,websocket,ext,overlay
etc/jetty.xml
etc/jetty-deploy.xml
etc/jetty-overlay.xml
----
The smarts of this are in etc/jetty-deploy.xml, which installs the
OverlayedAppProvider into the DeploymentManager. You can then start
Jetty normally:
The mechanics of this are in etc/jetty-deploy.xml, which installs the `OverlayedAppProvider` into the `DeploymentManager`.
Jetty can then be started normally:
[source, screen]
....
----
$ java -jar start.jar
....
----
Jetty is now listening on port 8080, but with no webapp deployed.
@ -141,71 +102,48 @@ ____
[[overlay-install]]
==== Installing the WebApp
You can download and deploy the WAR file for this demo using the
following commands, which essentially downloads and extracts the WAR
file to the $JETTY_HOME/overlays/webapps directory.
The WAR file for this demo can be downloaded and deployed the using the following commands, which downloads and extracts the WAR file to the $JETTY_HOME/overlays/webapps directory.
[source, screen]
....
----
$ cd /tmp
$ wget -O jtrac.zip http://sourceforge.net/projects/j-trac/files/jtrac/2.1.0/jtrac-2.1.0.zip/download
$ jar xfv jtrac.zip jtrac/jtrac.war
$ mv jtrac/jtrac.war $JETTY_HOME/overlays/webapps
----
....
When you have run these commands (or equivalent), you see in the Jetty
server window a message saying that the OverlayedAppProvider has
extracted and loaded the WAR file:
When these commands (or equivalent) have been executed, a message that the `OverlayedAppProvider` has extracted and loaded the WAR file will be displayed in the Jetty server window:
[source,plain]
----
2011-05-06 10:31:54.678:INFO:OverlayedAppProvider:Extract jar:file:/tmp/jetty-distribution-7.4.1-SNAPSHOT/overlays/webapps/jtrac-2.1.0.war!/ to /tmp/jtrac-2.1.0_236811420856825222.extract
2011-05-06 10:31:55.235:INFO:OverlayedAppProvider:loaded jtrac-2.1.0@1304641914666
----
Unlike the normal webapps dir, loading a WAR file from the
overlays/webapp dir does not deploy the web application. It simply makes
it available to use as the basis for templates and overlays.
Unlike the normal webapps dir, loading a WAR file from the overlays/webapp dir does not deploy the web application, it simply makes it available to use as the basis for templates and overlays.
==== Installing a Template Overlay
A template overlay is a WAR structured directory/archive that contains
just the files that you have added or modified to customize/configure
the web application for all instances you plan to deploy.
A template overlay is a WAR structured directory/archive that contains the files that have been added or modified to customize/configure the web application for all instances planned for deployment.
You can install the demo template from the downloaded files with the
command:
The demo template can be installed from the downloaded files with the command:
[source, screen]
....
----
$ mv $OVERLAYS/jtracTemplate\=jtrac-2.1.0 $JETTY_HOME/overlays/templates/
----
....
In the Jetty server window, you should see the template loaded with a
message like:
In the Jetty server window, a message similar to this will be displayed confirmed that the template is loaded:
[source,plain]
----
2011-05-06 11:00:08.716:INFO:OverlayedAppProvider:loaded jtracTemplate=jtrac-2.1.0@1304643608715
----
The contents of the loaded template are as follows:
[source,plain]
----
templates/jtracTemplate=jtrac-2.1.0
|__ WEB-INF
|__ classes
@ -214,44 +152,34 @@ templates/jtracTemplate=jtrac-2.1.0
|__ overlay.xml
|__ template.xml
|__ web-overlay.xml
----
name of the template directory (or WAR)::
Uses the ‘=’ character in jtracTemplate=jtrac-2.1.0 to separate the
name of the template from the name of the WAR file in webapps that it
applies to. If = is a problem, then you can instead use --.
Uses the ‘=’ character in jtracTemplate=jtrac-2.1.0 to separate the name of the template from the name of the WAR file in webapps that it applies to.
If = is a problem, use -- instead.
WEB-INF/classes/jtrac-init.properties::
Replaces the JTrac properties file with an empty file, as the
properties it contains are configured elsewhere.
Replaces the JTrac properties file with an empty file, as the properties it contains are configured elsewhere.
WEB-INF/log4j.properties::
Configures the logging for all instances of the template.
WEB-INF/overlay.xml::
A Jetty XML formatted IoC file that injects/configures the
ContextHandler for each instance. In this case it just sets up the
context path:
A Jetty XML formatted IoC file that injects/configures the `ContextHandler` for each instance. \
In this case it sets up the context path:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/</Set>
</Configure>
----
WEB-INF/template.xml::
a Jetty XML formatted IoC file that injects/configures the resource
cache and classloader that all instances of the template share. It
runs only once per load of the template:
A Jetty XML formatted IoC file that injects/configures the resource cache and classloader that all instances of the template share.
It runs only once per load of the template:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure class="org.eclipse.jetty.overlays.TemplateContext">
@ -262,19 +190,15 @@ WEB-INF/template.xml::
<Set name="maxCacheSize">64000000</Set>
</Get>
</Configure>
----
WEB-INF/web-overlay.xml::
a web.xml fragment that Jetty overlays on top of the web.xml from the
base WAR file; it can set init parameters and add/modify filters and
servlets. In this example it sets the application home and springs
rootKey:
A `web.xml` fragment that Jetty overlays on top of the `web.xml` from the base WAR file; it can set init parameters and add/modify filters and
servlets.
In this example it sets the application home and springs `webAppRootKey`:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -290,61 +214,43 @@ WEB-INF/web-overlay.xml::
</context-param>
<filter>
</web-app>
----
Notice the parameterisation of values such as
`${overlays.instance.classifier}`, as this allows the configuration to
be in the template, and not customised for each instance.
Notice the parameterization of values such as `${overlays.instance.classifier}`, as this allows the configuration to be in the template, and not customized for each instance.
Without the Overlay Deployer, you would still need to have configured
all of the above, but rather than being in a single clear structure the
configuration elements would have been either in the server's common
directory, the server's webdefaults.xml (aka server.xml), or baked into
the WAR file of each application instance using copied/modified files
from the original. The Overlay Deployer allows you to make all these
changes in one structure; moreover it allows you to parameterise some of
the configuration, which facilitates easy multi-tenant deployment.
Without the Overlay Deployer, all of the above would still need to have configure , but rather than being in a single clear structure the configuration elements would have been either in the server's common directory, the server's `webdefaults.xml` (aka `server.xml`), or baked into the WAR file of each application instance using copied/modified files from the original.
The Overlay Deployer allows all these changes to be made in one structure; moreover it allows for the parameterization of some of the configuration, which facilitates easy multi-tenant deployment.
==== Installing an Instance Overlay
Now that you have installed a template, you can install one or more
instance overlays to deploy the actual web applications:
Now that the template is installed, one or more instance overlays can be implemented to deploy the actual web applications:
[source, screen]
....
----
$ mv /tmp/overlays/instances/jtracTemplate\=blue $JETTY_HOME/overlays/instances/
$ mv /tmp/overlays/instances/jtracTemplate\=red $JETTY_HOME/overlays/instances/
$ mv /tmp/overlays/instances/jtracTemplate\=blue $JETTY_HOME/overlays/instances/
----
....
As each instance moves into place, you see the Jetty server window react
and deploy that instance. Within each instance, there is the structure:
As each instance moves into place, the Jetty server window reacts and deploys the instance.
Within each instance, there is the structure:
[source,plain]
----
instances/jtracTemplate=red/
|__ WEB-INF
| |__ overlay.xml
|__ favicon.ico
|__ resources
|__ jtrac.css
----
WEB-INF/overlay.xml::
a Jetty XML format IoC file that injects/configures the context for
the instance. In this case it sets up a virtual host for the instance:
A Jetty XML format IoC file that injects/configures the context for the instance.
In this case it sets up a virtual host for the instance:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -355,47 +261,30 @@ WEB-INF/overlay.xml::
</Array>
</Set>
</Configure>
----
favicon.ico::
Replaces the icon in the base WAR with one that has a theme for the
instance, in this case red, blue, or green.
Replaces the icon in the base WAR with one that has a theme for the instance; in this case red, blue, or green.
resources/jtrac.css::
Replaces the style sheet from the base WAR with one that his a theme
for the instance.
Replaces the style sheet from the base WAR with one that has a theme for the instance.
You can now view the deployed instances by pointing your browser at
http://127.0.0.1:8080, http://127.0.0.2:8080 and http://127.0.0.3:8080.
Deployed instances can be vied by pointing a browser at http://127.0.0.1:8080, http://127.0.0.2:8080 and http://127.0.0.3:8080.
The default username/password for JTrac is admin/admin.
[[overlay-tips]]
==== Things to Know and Notice
* Each instance has themes with images and style sheets from the
instance overlay.
* Each instance is running with its own application directory (that is,
/tmp/jtrac-red), set in templates web-overlay.xml.
* A virtual host set in the instance overlay.xml distinguishes the
instances.
* Each instance has themes with images and style sheets from the instance overlay.
* Each instance is running with its own application directory (that is, /tmp/jtrac-red), set in templates web-overlay.xml.
* A virtual host set in the instance overlay.xml distinguishes the instances.
* All instances share static content from the base WAR and template.
Specifically there is a shared ResourceCache so only a single instance
of each static content is loaded into memory.
* All instances share the classloader at the base WAR and template
level, so that only a single instance of common classes is loaded into
memory. You can configure classes with non shared statics to load in the
instances classloader.
Specifically there is a shared `ResourceCache` so only a single instance of each static content is loaded into memory.
* All instances share the classloader at the base WAR and template level, so that only a single instance of common classes is loaded into memory.
Classes with non shared statics can be configured to load in the instances classloader.
* Jetty hot deploys all overlays and tracks dependencies.
** If an XML changes in an instance, Jetty redeploys it.
** If an XML changes in a template, then Jetty redeploys all instances
using it.
** If a WAR file changes, then Jetty redeploys all templates and all
instances dependant on it.
* You can esaily deploy new versions. For example, when JTrac-2.2.0.war
becomes available, you can just drop it into overlays/webapps and then
rename jtracTemplate\=jtrac-2.1.0 to jtracTemplate\=jtrac-2.2.0
* There is a fuller version of this demo in overlays-demo-jndi.tar.gz,
that uses JNDI (needs options=jndi, annotations and jetty-plus.xml in
start.ini) and shows how you can add extra JARs in the overlays.
** If an XML changes in a template, then Jetty redeploys all instances using it.
** If a WAR file changes, then Jetty redeploys all templates and all instances dependent on it.
* New versions can be easily deployed.
For example, when JTrac-2.2.0.war becomes available, it can be placed into `overlays/webapps` and then rename `jtracTemplate\=jtrac-2.1.0` to `jtracTemplate\=jtrac-2.2.0`.
* There is a fuller version of this demo in overlays-demo-jndi.tar.gz, that uses JNDI (needs `options=jndi`, annotations and `jetty-plus.xml` in `start.ini`) and shows how additional JARs can be added in the overlays.

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

@ -17,52 +17,38 @@
[[quickstart-webapp]]
=== Quickstart Webapps
The auto discovery features of the Servlet specification can make
deployments slow and uncertain. 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.
The auto discovery features of the Servlet specification can make deployments slow and uncertain.
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, we have included the quickstart
module that 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:
From Jetty release 9.2.0.v20140526, the included quickstart module 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:
* ServletContainerInitializers
* HandlesTypes classes
* Taglib Descriptors
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.
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.
==== Setting up Quickstart
To use quickstart the module has to be available to your jetty instance.
In a maven project this is done just by adding a dependency on the
artifact ID jetty-quickstart or with a standard jetty distribution you
can run the command:
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]
....
----
$ java -jar $JETTY_HOME/start.jar --add-to-startd=quickstart
....
----
Also the webapps you deploy 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 your
web application already has a `webapps/myapp.xml` file, then you can
simply change the class in the Configure element, otherwise you can
create an `webapps/myapp.xml` file as follows:
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:
[source, xml]
____
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">
<Configure class="org.eclipse.jetty.quickstart.QuickStartWebApp">
@ -70,66 +56,49 @@ ____
<Set name="contextPath">/benchmark</Set>
<Set name="autoPreconfigure">true</Set>
</Configure>
____
----
==== 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. On subsequent
deployments, all the discovery steps are skipped and the
`quickstart-web.xml` is used directly to configure 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.
On subsequent deployments, all the discovery steps are skipped and the `quickstart-web.xml` is used directly to configure the web application.
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]
simply with the jetty-all-uber (aggregate) jar:
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]
....
----
$ java -cp jetty-all-@project.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 options for running it.
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
Of course precompiling JSPs is an excellent way to improve the start
time of a web application. Since jetty 9.2.0, the apache Jasper JSP
implementation has been used and has been augmented to allow the TLD
scan to be skipped. This can be done by adding a context-param to the
`web.xml` file (this is done automatically by the Jetty Maven JSPC
plugin):
Of course precompiling JSPs is an excellent way to improve the start time of a web application.
Since jetty 9.2.0, the Apache Jasper JSP implementation has been used and has been augmented to allow the TLD scan to be skipped.
This can be done by adding a `context-param` to the `web.xml` file (this is done automatically by the Jetty Maven JSPC plugin):
[source, xml]
____
----
<context-param>
<param-name>org.eclipse.jetty.jsp.precompiled</param-name>
<param-value>true</param-value>
</context-param>
____
----
==== Bypassing start.jar
The jetty start.jar mechanism is a very powerful and flexible mechanism
for constructing a classpath and executing a configuration encoded in
jetty XML format. However, this mechanism does take some time to build
the classpath. The start.jar mechanism can be bypassed by using the
`–dry-run` option to generate and reuse a complete command line to start
jetty at a later time:
The Jetty `start.jar` mechanism is a very powerful and flexible mechanism for constructing a `classpath` and executing a configuration encoded in Jetty XML format.
However, this mechanism does take some time to build the `classpath`.
The start.jar mechanism can be bypassed by using the `–dry-run` option to generate and reuse a complete command line to start Jetty at a later time:
[source, screen]
....
----
$ RUN=$(java -jar $JETTY_HOME/start.jar --dry-run)
$ eval $RUN
....
----
Note that `--dry-run` may create a properties file in the temp directory
and include it on the generated command line. If so, then a copy of the
temporary properties file should be taken and the command line updated
with it's new persistent location.
Note that `--dry-run` may create a properties file in the temp directory and include it on the generated command line.
If so, then a copy of the temporary properties file should be taken and the command line updated with it's new persistent location.

27
jetty-documentation/src/main/asciidoc/configuring/deploying/setting-deployment-bindings.adoc
View File

@ -17,24 +17,16 @@
[[setting-deployment-bindings]]
=== Setting Deployment Bindings
Jetty provides __deployment bindings__, which let you tap into the
application lifecycle of the DeploymentManager.
Jetty provides __deployment bindings__, which allows access to the application lifecycle of `DeploymentManager`.
There are a handful of bindings that exist within the core distribution
of jetty:
There are a handful of bindings that exist within the core distribution of Jetty:
* `StandardDeployer` (deploying)–Standard binding that deals with
deploying a webapp.
* `StandardStarter` (starting)–Standard binding that deals with starting
a webapp.
* `StandardStopper` (stopping)–Standard binding that deals with stopping
a webapp.
* `StandardUndeployer` (undeploying)–Standard undeployer that deals with
undeploying a webapp.
* `DebugBinding` (any specified)–Attaches a binding and prints logging
information of a context going through the specified binding target.
* `GlobalWebappConfigBinding` (deploying)–Allows the user to override
various settings of a webapp's context globally for all contexts.
* `StandardDeployer` (deploying)–Standard binding that deals with deploying a webapp.
* `StandardStarter` (starting)–Standard binding that deals with starting a webapp.
* `StandardStopper` (stopping)–Standard binding that deals with stopping a webapp.
* `StandardUndeployer` (undeploying)–Standard undeployer that deals with undeploying a webapp.
* `DebugBinding` (any specified)–Attaches a binding and prints logging information of a context going through the specified binding target.
* `GlobalWebappConfigBinding` (deploying)–Allows the user to override various settings of a webapp's context globally for all contexts.
+
[source,xml]
----
@ -47,5 +39,4 @@ various settings of a webapp's context globally for all contexts.
</Call>
----
* OrderedGroupBinding (any specified)–Allows the user to set a specific
order for bindings to process in a given binding target.
* OrderedGroupBinding (any specified)–Allows the user to set a specific order for bindings to process in a given binding target.

12
jetty-documentation/src/main/asciidoc/configuring/deploying/static-content-deployment.adoc
View File

@ -17,11 +17,8 @@
[[static-content-deployment]]
=== Configuring Static Content Deployment
Should you want to serve purely static content, you can use the Jetty
Deployment Descriptor XML concepts and the internal ResourceHandler to
setup simple serving of static content. Just create a file called
`scratch.xml` in the `${jetty.home}/webapps` directory and paste these
file contents in it.
To serve purely static content, the Jetty Deployment Descriptor XML concepts and the internal `ResourceHandler` can be used.
Create a file called `scratch.xml` in the `${jetty.home}/webapps` directory and paste the following file contents in it.
[source,xml]
----
@ -41,6 +38,5 @@ file contents in it.
----
This is a very basic setup for serving static files, if you want
advanced static file serving, use the
link:{JXURL}/org/eclipse/jetty/servlet/DefaultServlet.html[DefaultServlet].
This is a very basic setup for serving static files.
For advanced static file serving, use the link:{JXURL}/org/eclipse/jetty/servlet/DefaultServlet.html[DefaultServlet].