Difference between revisions of "Jetty/Reference/override-web.xml"

Revision as of 02:01, 29 June 2009

Introduction

override-web.xml is a file which is applied to a web application after the application's own WEB-INF/web.xml. It is defined per-webapp, and uses the web.xml syntax.

A common need is to be able to deploy the same unchanged webapp or WAR into different environments, while being able to customize the webapp for that environment. You can change the configuration using a jetty.xml file, to some extent, as jetty.xml does not form part of the webapp. It therefore can be changed per deployment. However, there are some things you might want to change that jetty.xml cannot help you with: for example, servlet init-params and context init-params. Using webdefault.xml won't help you either, because it is applied first, and so cannot override values inside the webapp's web.xml.

The solution is to use an override web.xml file. This is another whole or partial web.xml file that resides externally to the webapp. It is applied after the webapp's WEB-INF/web.xml file and can therefore override or add new elements.

Using override-web.xml

Jetty Standalone

You can specify the override-web.xml to be used for an individual web application, in that webapp's jetty-web.xml.

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  ...
  <!-- Set up the path to the custom override descriptor, 
  relative to your $(jetty.home) directory or to the current directory -->
  <Set name="overrideDescriptor"><SystemProperty name="jetty.home" default="."/>/my/path/to/override-web.xml</Set>
  ...
</Configure>

In code, this is:

import org.eclipse.jetty.webapp.WebAppContext;
 
    ...
 
    WebAppContext wac = new WebAppContext();
    ...
    //Set the path to the override descriptor, based on your $(jetty.home) directory
    wac.setOverrideDescriptor(System.getProperty("jetty.home")+"/my/path/to/override-web.xml");
    ...

Alternatively, use the classloader to get the path to the override descriptor as a resource.

Jetty Maven Plugin

Use the <overrideDescriptor> tag as follows:

<project>
    ...
    <plugins>
        <plugin>
            ...
            <artifactId>jetty-maven-plugin</artifactId>
            <configuration>
                <webAppConfig>
                  ...
                  <overrideDescriptor>src/main/resources/override-web.xml</overrideDescriptor>
                </webAppConfig>
            </configuration>
        </plugin>
        ...
    </plugins>
    ...
</project>

Additional Resources

• web.xml Syntax Reference reference for web.xml files
• webdefault.xml web.xml-formatted file, applied before the webapp's web.xml