Jetty provides capability to deploy an arbitrary context or web application with Jetty-specific configuration. The ContextProvider mechanism, which is now an extension of the core deployment infrastructure, implements this capability.
You can use the
ContextProvider
to (hot) deploy an arbitrary context or web application with Jetty-specific configuration. To statically
deploy only standard web applications at startup, use the WebAppProvider (see Using the WebApp Provider).
A jetty.xml file typically defines a ContextProvider; within the stock
jetty distribution the name of this file is jetty-contexts.xml:
<Configure id="Server" class="org.eclipse.jetty.server.Server"> <Ref id="DeploymentManager"> <Call name="addAppProvider"> <Arg> <New class="org.eclipse.jetty.deploy.providers.ContextProvider"> <Set name="monitoredDir"><Property name="jetty.home" default="." />/contexts</Set> <Set name="scanInterval">1</Set> </New> </Arg> </Call> </Ref> </Configure>
The ContextProvider scans the monitoredDir directory at intervals of
scanInterval seconds for XML descriptors that define contexts. It then deploys any contexts to the passed
contexts reference to a HandlerContainer, (normally an instance of
ContextHandlerCollection). The deployment descriptors are in Jetty/Reference/jetty.xml syntax|jetty xml
//TODO xref// format, and define and configure individual contexts. A minimal example is:
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/test</Set> <Set name="war"><SystemProperty name="jetty.home" default<nowiki>=</nowiki>"."/>/webapps/test</Set> </Configure>
This example creates an instance of
WebAppContext
and sets the contextPath to /test and the resourceBase to
$jetty.home/webapps/test. Because the context used is a standard web application context, when started it
inspects the resourceBase for a WEB-INF/web.xml for further configuration.
The ContextProvider is added to the server as a LifeCycle. This simply means that
the provider starts and stops with the server. That is, when server.start() is called,
start is also called on the provider.
The ContextProvider can automatically do property substitution on the context files that it
deploys. You define a ConfigurationManager that manages the properties and pass this into the
ContextProvider. There is currently one implementation of the ConfigurationManage, and that is
the org.eclipse.jetty.deployer.FileConfigurationManager, which reads a properties file and makes
available the property values to the ContextProvider. Here's how to configure the
ContextProvider:
<Configure id="Server" class="org.eclipse.jetty.server.Server"> <Ref id="DeploymentManager"> <Call name="addAppProvider"> <Arg> <New class="org.eclipse.jetty.deploy.providers.ContextProvider"> <Set name="monitoredDir"><Property name="jetty.home" default="." />/contexts</Set> <Set name="scanInterval">1</Set> <Set name="configurationManager"> <New class="org.mortbay.jetty.deployer.FileConfigurationManager"> <Set name="file"><SystemProperty name="jetty.home" default="."/>/foo.properties</Set> </New> </Set> </New> </Arg> </Call> </Ref> </Configure>
Here's an example of the contents of the foo.properties file:
foo = /funkyapp
Here's how you would use this in a context xml file:
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd"> <Configure class="org.mortbay.jetty.webapp.WebAppContext"> <Set name="contextPath"><Property name="foo"/></Set> <Set name="war"><SystemProperty name="jetty.home" default="."/>/webapps/test</Set> </Configure>
Because the class of the context is defined in the Configure clause, you can deploy any type of
ContextHandler with this mechanism, including base
ContextHandler,
ServletContextHandler
,
WebAppContext
, or any class derived from them.
If the scan interval is non-zero, the ContextProvider scans the configuration directory at that
interval (in seconds) for changes to the deployment descriptors. If you add a descriptor to the directory, it
deploys the new context. If you touch or update a descriptor, the provider stops, reconfigures, and redeploys its
context. If you remove a descriptor, the provider stops and removes its context from the server.
If the scan interval is zero, the ContextProvider scans the directory only at startup.
This mechanism allows you to call most of the API available on
ContextHandler
or its derived classes to configure the web application. Useful things to configure include:
setAttribute
setClassLoader
setContextPath
setVirtualHosts
addServlet
setConfigurations
setExtraClassPath
setDefaultsDescriptor
setDescriptor
setOverrideDescriptor
setSystemClasses
setServerClasses