Jump to: navigation, search

Difference between revisions of "Jetty/Feature/Hot Deployment"

< Jetty‎ | Feature
Line 1: Line 1:
 
{{Jetty Feature
 
{{Jetty Feature
 
| introduction = Jetty provides capability to deploy an arbitrary context or web application with Jetty-specific configuration. This capability is implemented via ContextDeployer mechanism.
 
| introduction = Jetty provides capability to deploy an arbitrary context or web application with Jetty-specific configuration. This capability is implemented via ContextDeployer mechanism.
| body = The ContextDeployer is typically defined in Jetty configuration file. It will scan a directory that contains xml descriptors that define contexts at a configured interval. Te
+
| body =
| more = (optional) - links, additional references
+
The [ContextDeployer http://dev.eclipse.org/viewcvs/index.cgi/jetty/trunk/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/ContextDeployer.java?root=RT_JETTY&view=markup] may be used to (hot)deploy an arbitrary Context or Web Application with Jetty specific configuration. To statically deploy only standard web applications at startup, use the [[JETTY/Feature/WebAppDeployer|WebAppDeployer].
 +
 
 +
==Overview==
 +
 
 +
Typically a ContextDeployer is defined in a jetty.xml file:
 +
 
 +
<source lang="xml">
 +
<Call name=<span class="code-quote">"addLifeCycle"</span>>
 +
  <Arg>
 +
    <New class=<span class="code-quote">"org.mortbay.jetty.deployer.ContextDeployer"</span>>
 +
      <Set name=<span class="code-quote">"contexts"</span>><Ref id=<span class="code-quote">"Contexts"</span>/></Set>
 +
      <Set name=<span class="code-quote">"configurationDir"</span>><SystemProperty name=<span class="code-quote">"jetty.home"</span> <span class="code-keyword">default</span><nowiki>=</nowiki><span class="code-quote">"."</span>/>/contexts</Set>
 +
      <Set name=<span class="code-quote">"scanInterval"</span>>1</Set>
 +
    </New>
 +
  </Arg>
 +
</Call>
 +
</source>
 +
 
 +
The ContextDeployer will scan the '''configurationDir''' directory at intervals of '''scanInterval''' seconds for xml descriptors that define contexts. Any contexts found are deployed to the passed '''contexts''' reference to a HandlerContainer (this is normally an instance of ContextHandlerCollection).
 +
 
 +
The deployment descriptors are in [Jetty/Reference/jetty.xml syntax|jetty xml] format and define and configure individual contexts. A minimal example is:
 +
 
 +
<source lang="xml">
 +
<?xml version=<span class="code-quote">"1.0"</span>  encoding=<span class="code-quote">"ISO-8859-1"</span>?>
 +
<!DOCTYPE Configure PUBLIC <span class="code-quote">"-<span class="code-comment">//Mort Bay Consulting//DTD Configure//EN"</span> <span class="code-quote">"http://jetty.mortbay.org/configure.dtd"</span>>
 +
</span><Configure class=<span class="code-quote">"org.eclipse.jetty.webapp.WebAppContext"</span>>
 +
  <Set name=<span class="code-quote">"contextPath"</span>>/test</Set>
 +
  <Set name=<span class="code-quote">"war"</span>><SystemProperty name=<span class="code-quote">"jetty.home"</span> <span class="code-keyword">default</span><nowiki>=</nowiki><span class="code-quote">"."</span>/>/webapps/test</Set>
 +
</Configure>
 +
</source>
 +
 
 +
This example creates an instance of [WebAppContext http://dev.eclipse.org/viewcvs/index.cgi/jetty/trunk/jetty-webapp/src/main/java/org/eclipse/jetty/webapp/WebAppContext.java?root=RT_JETTY&view=markup] and sets the '''contextPath''' to be "/test" and the '''resourceBase''' to be "$jetty.home/webapps/test". Because the context used is a standard web application context, when started it will inspect the resourceBase for a WEB-INF/web.xml for further configuration.
 +
 
 +
The ContextDeployer is added to the server as a LifeCycle. This simply means that the deployer will be started and stopped with the server. Ie when server.start() is called, then start will also be called on the deployer.
 +
 
 +
===Property value substitution===
 +
 
 +
The ContextDeployer 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 ContextDeployer. There is currently one implementation of the ConfigurationManager, and that is the <tt>org.mortbay.jetty.deployer.FileConfigurationManager</tt> that reads a properties file and makes available the property values to the ContextDeployer. Here's how you would configure the ContextDeployer:
 +
 
 +
<div class="code panel" style="border-width: 1px"><div class="codeContent panelContent">
 +
 
 +
 +
<Call name=<span class="code-quote">"addLifeCycle"</span>>
 +
  <Arg>
 +
    <New class=<span class="code-quote">"org.mortbay.jetty.deployer.ContextDeployer"</span>>
 +
      <Set name=<span class="code-quote">"contexts"</span>><Ref id=<span class="code-quote">"Contexts"</span>/></Set>
 +
      <Set name=<span class="code-quote">"configurationDir"</span>><SystemProperty name=<span class="code-quote">"jetty.home"</span> <span class="code-keyword">default</span><nowiki>=</nowiki><span class="code-quote">"."</span>/>/contexts</Set>
 +
      <Set name=<span class="code-quote">"scanInterval"</span>>1</Set>
 +
      <Set name=<span class="code-quote">"configurationManager"</span>>
 +
        <New class=<span class="code-quote">"org.mortbay.jetty.deployer.FileConfigurationManager"</span>>
 +
          <Set name=<span class="code-quote">"file"</span>><SystemProperty name=<span class="code-quote">"jetty.home"</span> <span class="code-keyword">default</span><nowiki>=</nowiki><span class="code-quote">"."</span>/>/foo.properties</Set>
 +
        </New>
 +
      </Set>
 +
    </New>
 +
  </Arg>
 +
</Call>
 +
 
 +
</div></div>
 +
 
 +
Here's an example of the contents of the foo.properties file:
 +
 
 +
<div class="code panel" style="border-width: 1px"><div class="codeContent panelContent">
 +
 
 +
 +
foo = /funkyapp
 +
 
 +
</div></div>
 +
 
 +
Here's how you would use this in a context xml file:
 +
 
 +
<div class="code panel" style="border-width: 1px"><div class="codeContent panelContent">
 +
 
 +
 +
<?xml version=<span class="code-quote">"1.0"</span>  encoding=<span class="code-quote">"ISO-8859-1"</span>?>
 +
<!DOCTYPE Configure PUBLIC <span class="code-quote">"-<span class="code-comment">//Mort Bay Consulting//DTD Configure//EN"</span> <span class="code-quote">"http://jetty.mortbay.org/configure.dtd"</span>>
 +
</span><Configure class=<span class="code-quote">"org.mortbay.jetty.webapp.WebAppContext"</span>>
 +
  <Set name=<span class="code-quote">"contextPath"</span>><Property name=<span class="code-quote">"foo"</span>/></Set>
 +
  <Set name=<span class="code-quote">"war"</span>><SystemProperty name=<span class="code-quote">"jetty.home"</span> <span class="code-keyword">default</span><nowiki>=</nowiki><span class="code-quote">"."</span>/>/webapps/test</Set>
 +
</Configure>
 +
 
 +
</div></div>
 +
 
 +
==Contexts==
 +
 
 +
Because the class of the context is defined in the Configure clause, any type of [http://jetty.mortbay.org/xref/org/mortbay/jetty/handler/ContextHandler.html ContextHandler] may be deployed with this mechanism, included base [http://jetty.mortbay.org/xref/org/mortbay/jetty/handler/ContextHandler.html ContextHandler]s, servlet [http://jetty.mortbay.org/xref/org/mortbay/jetty/servlet/Context.html Context]s, [http://jetty.mortbay.org/xref/org/mortbay/jetty/webapp/WebAppContext.html WebAppContexts] or any class derived from them.
 +
 
 +
==Hot deploy==
 +
 
 +
If the scan interval is non-zero, the configuration directory is scanned at that interval (in seconds) for changes to the deployment descriptors. If a descriptor is added to the directory, the new context will be deployed. If a descriptor is touched/updated then it's context will be stopped, reconfigured and redeployed. If a descriptor is removed, then it's context will be stopped and removed from the server.
 +
 
 +
If the scan interval is zero, then the directory is only scanned at startup.
 +
 
 +
==Other things to configure==
 +
 
 +
This mechanism allows the most of the API available on [http://jetty.mortbay.org/apidocs/org/mortbay/jetty/handler/ContextHandler.html ContextHandler] or its derived classes to be called to configure the web application. Useful things to configure include:
 +
 
 +
* setAttribute
 +
* setClassLoader
 +
* setContextPath
 +
* setVirtualHosts
 +
* addServlet
 +
* setConfigurations
 +
* setExtraClassPath
 +
* setDefaultsDescriptor
 +
* setDescriptor
 +
* setOverrideDescriptor
 +
* setSystemClasses
 +
* setServerClasses
 +
 
 
| category = [[Category:Jetty Feature]]
 
| category = [[Category:Jetty Feature]]
 
}}
 
}}

Revision as of 16:57, 18 June 2010

{{Jetty Feature | introduction = Jetty provides capability to deploy an arbitrary context or web application with Jetty-specific configuration. This capability is implemented via ContextDeployer mechanism. | body = The [ContextDeployer http://dev.eclipse.org/viewcvs/index.cgi/jetty/trunk/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/ContextDeployer.java?root=RT_JETTY&view=markup] may be used to (hot)deploy an arbitrary Context or Web Application with Jetty specific configuration. To statically deploy only standard web applications at startup, use the [[JETTY/Feature/WebAppDeployer|WebAppDeployer].

Overview

Typically a ContextDeployer is defined in a jetty.xml file:

 
 <Call name=<span class="code-quote">"addLifeCycle"</span>>
   <Arg>
     <New class=<span class="code-quote">"org.mortbay.jetty.deployer.ContextDeployer"</span>>
       <Set name=<span class="code-quote">"contexts"</span>><Ref id=<span class="code-quote">"Contexts"</span>/></Set>
       <Set name=<span class="code-quote">"configurationDir"</span>><SystemProperty name=<span class="code-quote">"jetty.home"</span> <span class="code-keyword">default</span><nowiki>=</nowiki><span class="code-quote">"."</span>/>/contexts</Set>
       <Set name=<span class="code-quote">"scanInterval"</span>>1</Set>
     </New>
   </Arg>
 </Call>

The ContextDeployer will scan the configurationDir directory at intervals of scanInterval seconds for xml descriptors that define contexts. Any contexts found are deployed to the passed contexts reference to a HandlerContainer (this is normally an instance of ContextHandlerCollection).

The deployment descriptors are in [Jetty/Reference/jetty.xml syntax|jetty xml] format and define and configure individual contexts. A minimal example is:

 <?xml version=<span class="code-quote">"1.0"</span>  encoding=<span class="code-quote">"ISO-8859-1"</span>?>
 <!DOCTYPE Configure PUBLIC <span class="code-quote">"-<span class="code-comment">//Mort Bay Consulting//DTD Configure//EN"</span> <span class="code-quote">"http://jetty.mortbay.org/configure.dtd"</span>>
 </span><Configure class=<span class="code-quote">"org.eclipse.jetty.webapp.WebAppContext"</span>>
   <Set name=<span class="code-quote">"contextPath"</span>>/test</Set>
   <Set name=<span class="code-quote">"war"</span>><SystemProperty name=<span class="code-quote">"jetty.home"</span> <span class="code-keyword">default</span><nowiki>=</nowiki><span class="code-quote">"."</span>/>/webapps/test</Set>
 </Configure>

This example creates an instance of [WebAppContext http://dev.eclipse.org/viewcvs/index.cgi/jetty/trunk/jetty-webapp/src/main/java/org/eclipse/jetty/webapp/WebAppContext.java?root=RT_JETTY&view=markup] and sets the contextPath to be "/test" and the resourceBase to be "$jetty.home/webapps/test". Because the context used is a standard web application context, when started it will inspect the resourceBase for a WEB-INF/web.xml for further configuration.

The ContextDeployer is added to the server as a LifeCycle. This simply means that the deployer will be started and stopped with the server. Ie when server.start() is called, then start will also be called on the deployer.

Property value substitution

The ContextDeployer 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 ContextDeployer. There is currently one implementation of the ConfigurationManager, and that is the org.mortbay.jetty.deployer.FileConfigurationManager that reads a properties file and makes available the property values to the ContextDeployer. Here's how you would configure the ContextDeployer:


<Call name="addLifeCycle">
  <Arg>
    <New class="org.mortbay.jetty.deployer.ContextDeployer">
      <Set name="contexts">Cite error: Invalid <ref> tag;
invalid names, e.g. too many