jetty-documentation/src/main/asciidoc/reference/jetty-xml/webdefault-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.
//  ========================================================================

[[webdefault-xml]]
=== `webdefault.xml`

The `webdefault.xml` file saves web applications from having to define a lot of house-keeping and container-specific elements in their own `web.xml` files.
For example, you can use it to set up mime-type mappings and JSP servlet-mappings.
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`.
It uses the xref:jetty-xml-config[] syntax.
Generally, it is convenient for all webapps in a Jetty instance to share the same `webdefault.xml` file.
However, it is certainly possible to provide differentiated ` webdefault.xml` files for individual web applications.

The `webdefault.xml` file is located in `$(jetty.home)/etc/webdefault.xml`.

[[using-webdefault-xml]]
==== Using `webdefault.xml`

You can specify a custom configuration file to use for specific webapps, or for all webapps. If you do not specify an alternate defaults descriptor, the $JETTY-HOME/etc/jetty-deploy.xml file will configure jetty to automatically use $JETTY_HOME/etc/`webdefault.xml`.

[[creating-custom-webdefault-xml-one-webapp]]
===== Creating a Custom `webdefault.xml` for One WebApp

You can specify a custom `webdefault.xml` for an individual web application in that webapp's xref:jetty-xml-config[] as follows:

[source, xml, subs="{sub-order}"]
----

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  ...
  <!-- Set up the absolute path to the custom webdefault.xml -->
  <Set name="defaultsDescriptor">/my/path/to/webdefault.xml</Set>
  ...
</Configure>


----

The equivalent in code is:

[source, java, subs="{sub-order}"]
----

import org.eclipse.jetty.webapp.WebAppContext;

    ...

    WebAppContext wac = new WebAppContext();
    ...
    //Set up the absolute path to the custom webdefault.xml.
    wac.setDefaultsDescriptor("/my/path/to/webdefault.xml");
    ...


----

Alternatively, you can use a xref:jetty-classloading[] to find the resource representing your custom `webdefault.xml`.

[[creating-custom-webdefault-xml-multiple-webapps]]
===== Creating a Custom `webdefault.xml` for Multiple WebApps

If you want to apply the same custom `webdefault.xml` to a number of webapps, provide the path to the file in xref:jetty-xml-config[] in the $JETTY_HOME/etc/jetty-deploy.xml file:

[source, xml, subs="{sub-order}"]
----
   <Set name="defaultsDescriptor"><Property name="jetty.home" default="." />/other/path/to/another/webdefault.xml</Set>
----

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

Similarly, when using the link:#jetty-maven-plugin[Jetty Maven Plugin] you provide a customized `webdefault.xml` file for your webapp as follows:

[source, xml, subs="{sub-order}"]
----

<project>
    ...
    <plugins>
        <plugin>
            ...
            <artifactId>jetty-maven-plugin</artifactId>
            <configuration>
                <webApp>
                  ...
                  <defaultsDescriptor>/my/path/to/webdefault.xml</defaultsDescriptor>
                </webApp>
            </configuration>
        </plugin>
        ...
    </plugins>
    ...
</project>


----

[[webdefault-xml-additional-resources]]
===== Additional Resources

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