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