Chapter 4 updates and corrections.
Signed-off-by: WalkerWatch <ctwalker@gmail.com>
This commit is contained in:
WalkerWatch
parent
183e3acabb
commit
f73423be9c
|
|
@ -17,7 +17,7 @@
|
|||
[[automatic-webapp-deployment]]
|
||||
=== Automatic Web Application Deployment
|
||||
|
||||
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.
|
||||
The most basic technique for deploying Web Applications is to put a WAR file or Exploded WAR directory into the `${jetty.base}/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.
|
||||
|
||||
|
|
@ -34,7 +34,7 @@ The Context Path assigned to this automatic deployment is based the filename (or
|
|||
|
||||
|`/webapps/belaying-pins/WEB-INF/web.xml` |http://host/belaying-pins/
|
||||
|
||||
|`/webapps/root.war` _(special name)_ |http://host/
|
||||
|`/webapps/root.war` _(reserved name)_ |http://host/
|
||||
|
||||
|`/webapps/root/WEB-INF/web.xml` _(special name)_ |http://host/
|
||||
|`/webapps/root/WEB-INF/web.xml` _(reserved name)_ |http://host/
|
||||
|=======================================================================
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@
|
|||
[[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).
|
||||
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]]
|
||||
|
|
@ -28,10 +28,10 @@ Jetty supports deploying Web Applications via XML files which will build an inst
|
|||
[[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.
|
||||
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.
|
||||
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::
|
||||
|
|
@ -69,7 +69,7 @@ ____
|
|||
</Configure>
|
||||
----
|
||||
|
||||
If the home path for an application needs altered, only the system property needs changed.
|
||||
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]]
|
||||
|
|
@ -78,7 +78,7 @@ This is useful if the version of an app is frequently changed.
|
|||
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 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, subs="{sub-order}"]
|
||||
|
|
@ -93,8 +93,8 @@ This can help make it clear that users should not make changes to the temporary
|
|||
</Configure>
|
||||
----
|
||||
|
||||
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.
|
||||
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, subs="{sub-order}"]
|
||||
|
|
@ -114,8 +114,8 @@ However, since the `web.xml` for the web application is processed after the depl
|
|||
</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.
|
||||
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, subs="{sub-order}"]
|
||||
|
|
@ -130,7 +130,7 @@ This feature is useful when adding parameters or additional Servlet mappings wit
|
|||
</Configure>
|
||||
----
|
||||
|
||||
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}"]
|
||||
|
|
@ -158,5 +158,5 @@ If the `web.xml` does not include a reference to this data source, an override d
|
|||
----
|
||||
|
||||
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.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -19,9 +19,9 @@
|
|||
|
||||
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), 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.
|
||||
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 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.
|
||||
|
||||
|
|
@ -40,7 +40,7 @@ The core feature of the `DeploymentManager` is the link:{JDURL}/org/eclipse/jett
|
|||
|
||||
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.
|
||||
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.
|
||||
|
|
@ -48,7 +48,7 @@ New applications enter this graph at the Undeployed node, and the link:{JDURL}/o
|
|||
[[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.
|
||||
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 can be developed include:
|
||||
|
|
@ -73,7 +73,7 @@ A fifth, non-standard binding, called link:{JDURL}/org/eclipse/jetty/deploy/bind
|
|||
[[default-web-app-provider]]
|
||||
==== Understanding the Default WebAppProvider
|
||||
|
||||
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[].
|
||||
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.
|
||||
|
|
@ -110,14 +110,14 @@ In the standard Jetty Distribution, this is configured in the `${jetty.home}/etc
|
|||
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.
|
||||
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::
|
||||
The file path or URL to the directory to scan for web applications.
|
||||
+
|
||||
|
||||
Scanning follows these rules:
|
||||
+
|
||||
|
||||
1. A base directory must exist.
|
||||
2. Hidden Files (starting with `"."`) are ignored.
|
||||
3. Directories with names ending in `".d"` are ignored.
|
||||
|
|
@ -131,19 +131,19 @@ monitoredDirName::
|
|||
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.
|
||||
|
||||
|
||||
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.
|
||||
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::
|
||||
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.
|
||||
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].
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -17,8 +17,8 @@
|
|||
[[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 jar files, `web.xml` and `web-fragment.xml` descriptors processed, and classes scanned for annotations amongst other things.
|
||||
As web applications have become more complex, Jetty has added ways to assist with customization by either broadening or lessening the amount of processing that is done at deployment time.
|
||||
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 other things.
|
||||
As web applications have become more complex, Jetty has 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].
|
||||
|
|
@ -26,8 +26,8 @@ If instead you're looking for information on how to configure a specific `WebApp
|
|||
[[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.
|
||||
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
|
||||
|
|
@ -55,31 +55,31 @@ META-INF/web-fragment.xml
|
|||
A Configuration class is called 5 times in different phases of the link:http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext's`] lifecycle:
|
||||
|
||||
preConfigure::
|
||||
As the `WebAppContext` is starting up this phase is executed.
|
||||
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.
|
||||
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`.
|
||||
deconfigure::
|
||||
This phase occurs whenever a `WebAppContext` is being stopped and allows the Configuration to undo any resources/metadata that it created.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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 shown, there is a default set of Configurations that support basic deployment of a webapp.
|
||||
As shown, there is a default set of Configurations that support basic deployment of a webapp.
|
||||
JavaEE features such as JNDI and advanced servlet spec features such as annotations have not been mentioned.
|
||||
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.
|
||||
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.
|
||||
|
|
@ -89,7 +89,7 @@ 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.
|
||||
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
|
||||
|
|
@ -102,7 +102,7 @@ To achieve that, we use 2 extra Configurations:
|
|||
|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.
|
||||
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 additional configuration is required, full details of which can be found link:#jndi[here].
|
||||
|
||||
====== Example: Annotation Configurations
|
||||
|
|
@ -117,7 +117,7 @@ We need just one extra Configuration class to help provide servlet annotation sc
|
|||
@WebListener etc
|
||||
|=======================================================================
|
||||
|
||||
The above configuration class must be _inserted immediately before_ the link:{JDURL}/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html[org.eclipse.jetty.webapp.JettyWebXmlConfiguration] class in the list of configurations.
|
||||
The above configuration class must 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 annotations additional configuration is require, details of which can be found link:#webapp-context-attributes[below.]
|
||||
|
||||
===== How to Set the List of Configurations
|
||||
|
|
@ -126,7 +126,7 @@ You have a number of options for how to make Jetty use a different list of Confi
|
|||
|
||||
====== Setting the list directly on the WebAppContext
|
||||
|
||||
If you have only one webapp that you wish to affect, this may be the easiest option.
|
||||
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:
|
||||
|
||||
|
|
@ -137,7 +137,7 @@ Let's see an example of how we would add in the Configurations for both JNDI _an
|
|||
|
||||
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
|
||||
|
||||
<Set name="war"><SystemProperty name="jetty.home" default="."/>/webapps/my-cool-webapp</Set>
|
||||
<Set name="war"><SystemProperty name="jetty.base" default="."/>/webapps/my-cool-webapp</Set>
|
||||
|
||||
<Set name="configurationClasses">
|
||||
<Array type="java.lang.String">
|
||||
|
|
@ -159,7 +159,7 @@ Of course, you can also use this method to reduce the Configurations applied to
|
|||
|
||||
====== 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].
|
||||
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, subs="{sub-order}"]
|
||||
|
|
@ -178,7 +178,7 @@ They will then be applied to each `WebAppContext` deployed by the deployer:
|
|||
<Call id="webappprovider" name="addAppProvider">
|
||||
<Arg>
|
||||
<New class="org.eclipse.jetty.deploy.providers.WebAppProvider">
|
||||
<Set name="monitoredDirName"><Property name="jetty.home" default="." />/webapps</Set>
|
||||
<Set name="monitoredDirName"><Property name="jetty.base" default="." />/webapps</Set>
|
||||
<Set name="configurationClasses">
|
||||
<Array type="java.lang.String">
|
||||
<Item>org.eclipse.jetty.webapp.WebInfConfiguration</Item>
|
||||
|
|
@ -202,8 +202,8 @@ They will then be 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.
|
||||
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, subs="{sub-order}"]
|
||||
|
|
@ -247,9 +247,9 @@ addBefore::
|
|||
|
||||
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.
|
||||
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.
|
||||
|
|
@ -276,8 +276,8 @@ Note that the order of the patterns defines the ordering of the scanning of the
|
|||
[[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.
|
||||
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 a xml file of a pattern that matches any jar that starts with `spring-`:
|
||||
|
|
|
|||
|
|
@ -17,9 +17,9 @@
|
|||
[[hot-deployment]]
|
||||
=== Hot Deployment
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
This behavior can be controlled by configuring `WebAppProvider` properties.
|
||||
|
|
@ -35,7 +35,8 @@ The default location for this configuration is in the `${jetty.home}/etc/jetty-d
|
|||
[source, xml, subs="{sub-order}"]
|
||||
----
|
||||
<?xml version="1.0"?>
|
||||
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">
|
||||
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
|
||||
|
||||
<Configure id="Server" class="org.eclipse.jetty.server.Server">
|
||||
|
||||
<Call name="addBean">
|
||||
|
|
@ -46,16 +47,16 @@ The default location for this configuration is in the `${jetty.home}/etc/jetty-d
|
|||
</Set>
|
||||
<Call name="setContextAttribute">
|
||||
<Arg>org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern</Arg>
|
||||
<Arg>.*/servlet-api-[^/]*\.jar$</Arg>
|
||||
<Arg>.*/[^/]*servlet-api-[^/]*\.jar$|.*/javax.servlet.jsp.jstl-.*\.jar$|.*/org.apache.taglibs.taglibs-standard-impl-.*\.jar$</Arg>
|
||||
</Call>
|
||||
|
||||
<Call id="webappprovider" name="addAppProvider">
|
||||
<Arg>
|
||||
<New class="org.eclipse.jetty.deploy.providers.WebAppProvider">
|
||||
<Set name="monitoredDirName"><Property name="jetty.home" default="." />/webapps</Set>
|
||||
<Set name="monitoredDirName"><Property name="jetty.base" default="." />/<Property name="jetty.deploy.monitoredDir" deprecated="jetty.deploy.monitoredDirName" default="webapps"/></Set>
|
||||
<Set name="defaultsDescriptor"><Property name="jetty.home" default="." />/etc/webdefault.xml</Set>
|
||||
<Set name="scanInterval">1</Set>
|
||||
<Set name="extractWars">true</Set>
|
||||
<Set name="scanInterval"><Property name="jetty.deploy.scanInterval" default="1"/></Set>
|
||||
<Set name="extractWars"><Property name="jetty.deploy.extractWars" default="true"/></Set>
|
||||
</New>
|
||||
</Arg>
|
||||
</Call>
|
||||
|
|
|
|||
|
|
@ -19,10 +19,10 @@
|
|||
|
||||
____
|
||||
[NOTE]
|
||||
This feature is reintroduced in Jetty 9.0.4
|
||||
This feature was reintroduced in Jetty 9.0.4
|
||||
____
|
||||
|
||||
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.
|
||||
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:
|
||||
|
||||
* WAR files can be kept immutable, even signed, so that it is clear which version is deployed.
|
||||
|
|
@ -44,27 +44,27 @@ Customizing, configuring and deploying a web application bundled as a WAR file f
|
|||
* Adding Jars to the container classpath for Datasource and other resources.
|
||||
* Modifying the container configuration to provide JNDI resources.
|
||||
|
||||
The result is that the customizations and configurations blend into both the container and the WAR file.
|
||||
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 filed can be added or replaced.
|
||||
To solve the problems highlighted above, Jetty introduced 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.
|
||||
The demonstation can be expanded 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 demonstration can be expanded on top of the Jetty distribution; this tutorial expands it to /tmp and installs the components step-by-step:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
$ cd /tmp
|
||||
$ wget http://webtide.intalio.com/wp-content/uploads/2011/05/overlays-demo.tar.gz
|
||||
$ wget http://webtide.com/wp-content/uploads/2011/05/overlays-demo.tar.gz
|
||||
$ tar xfvz overlays-demo.tar.gz
|
||||
$ export OVERLAYS=/tmp/overlays
|
||||
----
|
||||
|
|
@ -72,8 +72,8 @@ $ export OVERLAYS=/tmp/overlays
|
|||
[[overlay-configure]]
|
||||
==== Configuring Jetty for Overlays
|
||||
|
||||
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.
|
||||
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, subs="{sub-order}"]
|
||||
|
|
@ -84,7 +84,7 @@ etc/jetty-deploy.xml
|
|||
etc/jetty-overlay.xml
|
||||
----
|
||||
|
||||
The mechanics of this are in etc/jetty-deploy.xml, which installs the `OverlayedAppProvider` into the `DeploymentManager`.
|
||||
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, subs="{sub-order}"]
|
||||
|
|
@ -96,7 +96,7 @@ Jetty is now listening on port 8080, but with no webapp deployed.
|
|||
|
||||
____
|
||||
[IMPORTANT]
|
||||
You should conduct the rest of the tutorial in another window with the JETTY_HOME environment set to the jetty distribution directory.
|
||||
You should conduct the rest of the tutorial in another window with the JETTY_HOME environmental variable set to the Jetty distribution directory.
|
||||
____
|
||||
|
||||
[[overlay-install]]
|
||||
|
|
@ -155,7 +155,7 @@ templates/jtracTemplate=jtrac-2.1.0
|
|||
----
|
||||
|
||||
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.
|
||||
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.
|
||||
|
|
@ -175,7 +175,7 @@ WEB-INF/overlay.xml::
|
|||
----
|
||||
|
||||
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.
|
||||
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, subs="{sub-order}"]
|
||||
|
|
@ -194,7 +194,7 @@ WEB-INF/template.xml::
|
|||
|
||||
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.
|
||||
servlets.
|
||||
In this example it sets the application home and springs `webAppRootKey`:
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
|
|
@ -218,7 +218,7 @@ WEB-INF/web-overlay.xml::
|
|||
|
||||
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, 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.
|
||||
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
|
||||
|
|
@ -232,7 +232,7 @@ $ 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, the Jetty server window reacts and deploys the instance.
|
||||
As each instance moves into place, the Jetty server window reacts and deploys the instance.
|
||||
Within each instance, there is the structure:
|
||||
|
||||
[source, plain, subs="{sub-order}"]
|
||||
|
|
@ -246,7 +246,7 @@ instances/jtracTemplate=red/
|
|||
----
|
||||
|
||||
WEB-INF/overlay.xml::
|
||||
A Jetty XML format IoC file that injects/configures the context 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, subs="{sub-order}"]
|
||||
|
|
@ -279,12 +279,12 @@ The default username/password for JTrac is admin/admin.
|
|||
* 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.
|
||||
* 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 dependent on it.
|
||||
* New versions can be easily deployed.
|
||||
* 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.
|
||||
|
|
|
|||
|
|
@ -17,8 +17,8 @@
|
|||
[[static-content-deployment]]
|
||||
=== Configuring Static Content Deployment
|
||||
|
||||
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.
|
||||
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.base}/webapps` directory and paste the following file contents in it.
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
----
|
||||
|
|
|
|||
Loading…
Reference in New Issue