Overlays

Overlays are used to share common resources across multiple web applications. The dependencies of a WAR project are collected in WEB-INF/lib, except for WAR artifacts which are overlayed on the WAR project itself.

Overlays at a glance

To demonstrate, given this structure for the project documentedproject:

 |-- pom.xml
 `-- src
     `-- main
         |-- java
         |   `-- com
         |       `-- example
         |           `-- projects
         |               `-- SampleAction.java
         |-- resources
         |   |-- images
         |   |   `-- sampleimage.jpg
         |   `-- sampleresource
         `-- webapp
             |-- WEB-INF
             |   `-- web.xml
             |-- index.jsp
             `-- jsp
                 `-- websource.jsp

The project depends on another WAR artifact, documentedprojectdependency-1.0-SNAPSHOT.war, which is declared as a dependency in the project's pom.xml:

  ...
  <dependencies>
    <dependency>
      <groupId>com.example.projects</groupId>
      <artifactId>documentedprojectdependency</artifactId>
      <version>1.0-SNAPSHOT</version>
      <type>war</type>
      <scope>runtime</scope>
    </dependency>
    ...
  </dependencies>
  ...

The structure for the documentedprojectdependency WAR file looks like this:

documentedprojectdependency-1.0-SNAPSHOT.war
 |-- META-INF
 |   |-- MANIFEST.MF
 |   `-- maven
 |       `-- com.example.projects
 |           `-- documentedprojectdependency
 |               |-- pom.properties
 |               `-- pom.xml
 |-- WEB-INF
 |   |-- classes
 |   |   |-- com
 |   |   |   `-- example
 |   |   |       `-- projects
 |   |   |           `-- SampleActionDependency.class
 |   |   `-- images
 |   |       `-- sampleimage-dependency.jpg
 |   `-- web.xml
 `-- index-dependency.jsp

The resulting WAR would end up like this:

 |-- META-INF
 |   |-- MANIFEST.MF
 |   `-- maven
 |       `-- com.example.projects
 |           `-- documentedproject
 |               |-- pom.properties
 |               `-- pom.xml
 |-- WEB-INF
 |   |-- classes
 |   |   |-- com
 |   |   |   `-- example
 |   |   |       `-- projects
 |   |   |           |-- SampleAction.class
 |   |   |           `-- SampleActionDependency.class
 |   |   `-- images
 |   |       |-- sampleimage-dependency.jpg
 |   |       `-- sampleimage.jpg
 |   `-- web.xml
 |-- index-dependency.jsp
 |-- index.jsp
 `-- jsp
     `-- websource.jsp

The web.xml file above comes from documentedproject.

Overlay types

The WAR Plugin handles both war and zip artifacts as overlays. However, for backward compatibility reasons, zip overlays are handled only if they are defined explicitly in the plugin's configuration.

Configuring Overlays

In previous versions of the WAR Plugin, no configuration was necessary. This is still the case if you are happy with the default settings. However, if you need more control, read on!

The <overlay> element can have the following child elements:

  • id - the id of the overlay. If none is provided, the WAR Plugin will generate one.
  • groupId - the groupId of the overlay artifact you want to configure.
  • artifactId - the artifactId of the overlay artifact you want to configure.
  • type - the type of the overlay artifact you want to configure. Default value is: war.
  • classifier - the classifier of the overlay artifact you want to configure if multiple artifacts matches the groupId/artifactId.
  • includes - the files to include. By default, all files are included.
  • excludes - the files to exclude. By default, the META-INF/MANIFEST.MF file is excluded.
  • targetPath - the target relative path in the webapp structure, which is only available for overlays of type war. By default, the content of the overlay is added in the root structure of the webapp.
  • skip - set to true to skip this overlay. Default value is: false.
  • filtered - whether to apply filtering to this overlay. Default value is false.

For instance, to exclude the sampleimage-dependency.jpg of our documentedprojectdependency war overlay above:

  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
          <overlays>
            <overlay>
              <groupId>com.example.projects</groupId>
              <artifactId>documentedprojectdependency</artifactId>
              <excludes>
                <exclude>WEB-INF/classes/images/sampleimage-dependency.jpg</exclude>
              </excludes>
            </overlay>
          </overlays>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...

Overlays packaging

Overlays are applied with a first-win strategy (hence if a file has been copied by one overlay, it won't be copied by another). Overlays are applied in the order in which they are defined in the <overlays> configuration. If no configuration is provided, the order in which the dependencies are defined in the POM is used (warning: this is not deterministic, especially if you have overlays as transitive dependencies). In case of a mixed situation (e.g. configured overlays and non-configured overlays), non-configured overlays are applied after configured overlays.

By default, the source of the project (a.k.a the current build) is added first (e.g. before any overlay is applied). The current build is defined as a special overlay with no groupId, artifactId. If overlays need to be applied first, simply configure the current build after those overlays.

For instance, if my-webapp from the com.example.projects group is a dependency of the project and needs to be applied before the project's own source, do as follows:

  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
          <overlays>
            <overlay>
              <groupId>com.example.projects</groupId>
              <artifactId>my-webapp</artifactId>
            </overlay>
            <overlay>
              <!-- empty groupId/artifactId represents the current build -->
            </overlay>
          </overlays>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...

Note: In the scenario above, any other WAR dependency will be applied after the current build since they have not been configured in the <overlays> element.

To perform an even more fine grained overwriting policy, overlays can be packaged multiple times with different includes/excludes. For instance if the index.jsp file of the overlay my-webapp must be set in the webapp but other files can be controlled the regular way, define two overlay configurations for my-webapp:

  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
          <overlays>
            <overlay>
              <id>my-webapp-index.jsp</id>
              <groupId>com.example.projects</groupId>
              <artifactId>my-webapp</artifactId>
              <includes>
                <include>index.jsp</include>
              </includes>
            </overlay>
            <overlay>
              <!-- empty groupId/artifactId represents the current build -->
            </overlay>

            <!-- Other overlays here if necessary -->

            <overlay>
              <id>my-webapp</id>
              <groupId>com.example.projects</groupId>
              <artifactId>my-webapp</artifactId>
            </overlay>
          </overlays>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...

Overlay global settings

The following settings can be specified globally and modify the way all overlays are applied:

  • workDirectory - sets the directory where overlays will be temporarily extracted. 
        ...
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
          <!-- default value is target/war/work -->
          <workDirectory>/tmp/extract_here</workDirectory>
        </configuration>
       </plugin>
    </plugins>
    ...
  • useCache - set to true to enable the webapp structure cache. Default value is: false. 
        ...
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
          <useCache>true</useCache>
        </configuration>
       </plugin>
    </plugins>
    ...

Zip dependencies with overlays

To use a zip dependency as an overlay you have to configure it explicitly in the plugin's configuration. For instance to inject the content of a zip overlay in the scripts directory of the webapp, do as follows:

    ...
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
          <overlays>
            <overlay>
              <groupId>zipGroupId</groupId>
              <artifactId>zipArtifactId</artifactId>
              <type>zip</type>
              <targetPath>scripts</targetPath>
            </overlay>
          </overlays>
        </configuration>
      </plugin>
    </plugins>
    ...