//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

[[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`.

____
[NOTE]
To ensure your `webdefault.xml` files are validated, you will need to set the `validateXml` attribute to true as described link:#jetty-xml-dtd[here.]
____

The `webdefault.xml` link:{GITBROWSURL}/jetty-webapp/src/main/config/etc/webdefault.xml[included with the Jetty Distribution] contains several configuration options, such as init params and servlet mappings, and is separated into sections for easy navigation.
Some of the more common options include, but are not limited to:

dirAllowed::
If true, directory listings are returned if no welcome file is found.
Otherwise 403 Forbidden displays.
precompressed::
If set to a comma separated list of file extensions, these indicate compressed formats that are known to map to a MIME-type that may be listed in a requests Accept-Encoding header.
If set to a boolean True, then a default set of compressed formats will be used, otherwise no pre-compressed formats.
maxCacheSize::
Maximum total size of the cache or 0 for no cache.
maxCachedFileSize::
Maximum size of a file to cache.
maxCachedFiles::
Maximum number of files to cache.

[[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
