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

From Eclipsepedia

Jump to: navigation, search
m
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{Jetty Reference
 
{{Jetty Reference
| introduction = <tt>override-web.xml</tt> 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 same syntax as a web.xml file.
+
| introduction =  
  
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 <tt>[[Jetty/References/jetty.xml|jetty.xml]]</tt> file, to some extent, as <tt>jetty.xml</tt> 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 <tt>jetty.xml</tt> cannot help you with: for example, servlet init-params and context init-params. Using <tt>[[Jetty/References/webdefault.xml|webdefault.xml]]</tt> won't help you either, because it is applied first, and so cannot override values inside the webapp's <tt>web.xml</tt>.
+
{{Jetty Redirect|http://www.eclipse.org/jetty/documentation/current/override-web-xml.html}}
  
The solution is to use an '''override web.xml''' file. This is another whole or partial <tt>web.xml</tt> file that resides externally to the webapp. It is applied after the webapp's <tt>WEB-INF/web.xml</tt> file and can therefore override or add new elements.
+
To deploy a web application or WAR into different environments, most likely you will need to customize the webapp for compatibility with each environment. The challenge is to do so without changing the webapp itself. You can use a <tt>jetty.xml</tt> file for some of this work since it is not part of the webapp. But there are some changes that <tt>jetty.xml</tt> cannot accomplish, for example, modifications to servlet init-params and context init-params. Using <tt>webdefault.xml</tt> is not an option because Jetty applies <tt>webdefault.xml</tt> to a web application ''before'' the application's own <tt>WEB-INF/web.xml</tt>, which means that it cannot override values inside the webapp's <tt>web.xml</tt>.
 +
 
 +
The solution is <tt>override-web.xml</tt>. It is a <tt>web.xml</tt> file that Jetty applies to a web application ''after'' the application's own <tt>WEB-INF/web.xml</tt>, which means that it can override values or add new elements. You define it per-webapp, using the [[Jetty/Reference/web.xml syntax|<tt>web.xml syntax</tt>]].
  
 
| body =  
 
| body =  
Line 10: Line 12:
 
== Using <tt>override-web.xml</tt> ==
 
== Using <tt>override-web.xml</tt> ==
  
=== Jetty Standalone ===
+
You can specify the <tt>override-web.xml</tt> to use for an individual web application, in that webapp's [[Jetty/Reference/jetty-web.xml|jetty-web.xml]].  
 
+
You can specify the <tt>override-web.xml</tt> to be used for an individual web application, in that webapp's [[Jetty/References/jetty-web.xml|jetty-web.xml]].  
+
  
 
<source lang="xml">
 
<source lang="xml">
Line 24: Line 24:
 
</source>
 
</source>
  
In code, this is:
+
The equivalent in code is:
  
 
<source lang="java">
 
<source lang="java">
Line 40: Line 40:
 
Alternatively, use the classloader to get the path to the override descriptor as a resource.
 
Alternatively, use the classloader to get the path to the override descriptor as a resource.
  
=== Jetty Maven Plugin ===
+
=== Using the Jetty Maven Plugin ===
  
 
Use the <code><overrideDescriptor></code> tag as follows:
 
Use the <code><overrideDescriptor></code> tag as follows:
Line 64: Line 64:
  
 
| more =  
 
| more =  
* [[Jetty/References/webdefault.xml|webdefault.xml]] web.xml-formatted file, applied before the webapp's web.xml
+
* [[Jetty/Reference/web.xml syntax|web.xml Syntax Reference]] reference for web.xml files
 
+
* [[Jetty/Reference/webdefault.xml|webdefault.xml]] web.xml-formatted file, applied before the webapp's web.xml
 
}}
 
}}

Latest revision as of 15:44, 23 April 2013



Contents

[edit] Introduction


To deploy a web application or WAR into different environments, most likely you will need to customize the webapp for compatibility with each environment. The challenge is to do so without changing the webapp itself. You can use a jetty.xml file for some of this work since it is not part of the webapp. But there are some changes that jetty.xml cannot accomplish, for example, modifications to servlet init-params and context init-params. Using webdefault.xml is not an option because Jetty applies webdefault.xml to a web application before the application's own WEB-INF/web.xml, which means that it cannot override values inside the webapp's web.xml.

The solution is override-web.xml. It is a web.xml file that Jetty applies to a web application after the application's own WEB-INF/web.xml, which means that it can override values or add new elements. You define it per-webapp, using the web.xml syntax.

Using override-web.xml

You can specify the override-web.xml to use 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>

The equivalent in code 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.

Using the 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