jetty-documentation/src/main/asciidoc/reference/jetty-xml/override-web-xml.adoc

//  ========================================================================
//  Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd.
//  ========================================================================
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================

[[override-web-xml]]
=== Jetty `override-web.xml`

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.
This is defined on a per-webapp basis, using the xref:jetty-xml-syntax[].

[[using-override-web-xml]]
==== Using override-web.xml

You can specify the `override-web.xml` to use for an individual web application in a deployable xml file located in Jetty webapps folder .
For example, if you had a webapp named MyApp, you would place a deployable xml file named `myapp.xml` in `${jetty.base}/webapps` which includes an `overrideDescriptor` entry for the `override-web.xml` file.

[source, xml, subs="{sub-order}"]
----
<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:

[source, java, subs="{sub-order}"]
----
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, you can use the classloader (xref:jetty-classloading[]) to get the path to the override descriptor as a resource.

[[override-using-jetty-maven-plugin]]
==== Using the Jetty Maven Plugin

Use the `<overrideDescriptor>` tag as follows:

[source, xml, subs="{sub-order}"]
----
<project>
    ...
    <plugins>
        <plugin>
            ...
            <artifactId>jetty-maven-plugin</artifactId>
            <configuration>
                <webAppConfig>
                  ...
                  <overrideDescriptor>src/main/resources/override-web.xml</overrideDescriptor>
                </webAppConfig>
            </configuration>
        </plugin>
        ...
    </plugins>
    ...
</project>
----

[[override-web-xml-additional-resources]]
==== Additional Resources

* xref:webdefault-xml[] –Information for this `web.xml` -formatted file, applied before the webapp's `web.xml` webapp.
* xref:jetty-xml-config[] –Reference for `jetty.xml` files