Overlays

Overlays are meant to share common resources accross multiple web applications. In general, all dependencies of a war project are collected in WEB-INF/lib except for war artifacts that are overlayed on the war source.

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!

Overlays at a glance

To demonstrate, given this project structure:

 .
 |-- 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 documentedprojectdependency-1.0-SNAPSHOT.war:

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

Assuming that you've declared the war artifact as a dependency in your 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 resulting war would end up like this:

 |-- META-INF
 |   |-- MANIFEST.MF
 |   `-- maven
 |       `-- com.example.projects
 |           |-- documentedproject
 |           |   |-- pom.properties
 |           |   `-- pom.xml
 |           `-- documentedprojectdependency
 |               |-- 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

Overlay types

The war plugin handles both war and zip artifacts. However, for backard compatibility reason, zip overlays are handled only if they are defined explicitely in the plugin's configuration.

Configuring Overlays

The overlay element can be configured as follows:

  • id - sets the id of the overlay. If none is provided, the war plugin will generate one.
  • groupId - sets the groupId of the overlay artifact you want to configure.
  • artifactId - sets the artifactId of the overlay artifact you want to configure.
  • type - sets the type of the overlay artifact you want to configure. By default, war.
  • classifier - sets the classifier of the overlay artifact you want to configure if multiple artifacts matches the groupId/artifact.
  • includes - sets the files to include. By default, all files are included.
  • excludes - sets the files to exclude. By default, the META-INF directory is excluded.
  • targetPath - sets the target relative path in the webapp structure, which is only available for war overlays. 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 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>
        <configuration>
          <overlays>
            <overlay>
              <groupId>com.example.projects</groupId>
              <artifactId>documentedprojectdependency</artifactId>
              <excludes>
                <exclude>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 an overlay, it won't be copied anymore). Overlays are applied in the order in which they are defined in the overlays configuration. If no configuration is provided, the order in which they are defined in the dependencies 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 added 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 source, do as follows:

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

Note that in the scenario above, any other overlay will be applied after the current build since they have not been configured in the overlays section.

To perform an even 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 overlays configuration for my-webapp:

  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <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 detected as 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 further the way overlays are applied.

  • dependentWarIncludes - sets the default includes to apply to all overlays. Any overlay that has no specific includes section inherit this settings by default.
        ...
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <dependentWarIncludes>**/IncludeME,**/images</dependentWarIncludes>
        </configuration>
       </plugin>
    </plugins>
    ...
  • dependentWarExcludes - sets the default excludes to apply to all overlays. Any overlay that has no specific excludes section inherit this settings by default.
        ...
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <dependentWarExcludes>WEB-INF/web.xml,index.*</dependentWarExcludes>
        </configuration>
       </plugin>
    </plugins>
    ...
  • workDirectory - sets the directory where overlays will be temporarily extracted.
        ...
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <!-- default value is target/war/work -->
          <workDirectory>/tmp/extract_here</workDirectory>
        </configuration>
       </plugin>
    </plugins>
    ...
  • useCache - set to false to disable the webapp structure cache. Defaults to true.
        ...
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <useCache>false</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>
        <configuration>
          <overlays>
            <overlay>
              <groupId>zipGroupId</groupId>
              <artifactId>zipArtifactId</artifactId>
              <type>zip</type>
              <targetPath>scripts</targetPath>
            </overlay>
          </overlays>
        </configuration>
      </plugin>
    </plugins>
    ...