Configuring a Specific Web Application Deployment

Configuring a Specific Web Application Deployment
Prev	Chapter 7. Deploying to Jetty	Next

Jetty Deployable Descriptor XML File

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 Jetty Deployable Descriptor XML File to accomplish such tuning.

Jetty Deployable Descriptor XML File

Jetty supports deploying Web Applications via XML file which will build an instance of a ContextHandler that Jetty can then deploy.

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.

The deployment descriptor file itself is an xml file that configures a WebAppContext class. For a basic installation you probably need to set only two properties:

war: the filesystem path to the web application file (or directory)
contextPath: 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:

<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/wiki</Set>
  <Set name="war">/opt/myapp/myapp.war</Set>
</Configure>

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:

<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/wiki</Set>
  <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set>
</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.

Configuring Advanced Descriptor Files

If you look at the documentation for the 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.

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.

<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/wiki</Set>
  <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set>
  <Set name="extractWAR">false</Set>
</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 like-named attributes from the deployment descriptor.

<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/wiki</Set>
  <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set>
  <Get name="ServletContext">
     <Call name="setInitParameter">
       <Arg>myapp.config</Arg>
       <Arg><SystemProperty name="myapp.home">/config/app-config.xml</Arg>
    </Call>
  </Get>
</Configure>

The following example sets a special web.xml override descriptor. This descriptor is processed after the web application's web.xml, so may override like-named attributes. This feature is useful if you want to add parameters or additional Servlet mappings without breaking open a packed WAR file.

<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/wiki</Set>
  <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set>
  <Set name="overrideDescriptor">/opt/myapp/overlay-web.xml</Set>
</Configure>

The next example configures not only the web application context, but also a database connection pool (see 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.

<?xml version="1.0"  encoding="ISO-8859-1"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Set name="contextPath">/wiki</Set>
  <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set>
</Configure>

<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
  <Arg></Arg>
  <Arg>jdbc/DSTest</Arg>
  <Arg>
    <New class="org.apache.commons.dbcp.BasicDataSource">
      <Set name="driverClassName">org.some.Driver</Set>
      <Set name="url">jdbc.url</Set>
      <Set name="username">jdbc.user</Set>
      <Set name="password">jdbc.pass</Set>
    </New>
  </Arg>
</New>

Prev	Up	Next
Automatic Web Application Deployment	Home	Configuring Static Content Deployment