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.
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:
<project> ... <dependencies> <dependency> <groupId>com.example.projects</groupId> <artifactId>documentedprojectdependency</artifactId> <version>1.0-SNAPSHOT</version> <type>war</type> <scope>runtime</scope> </dependency> ... </dependencies> ... </project>
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.
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.
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:
For instance, to exclude the sampleimage-dependency.jpg of our documentedprojectdependency war overlay above:
<project> ... <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.1</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> ... </project>
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:
<project> ... <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.1</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> ... </project>
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:
<project> ... <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.1</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> ... </project>
The following settings can be specified globally and modify the way all overlays are applied.
<project> ... <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.1</version> <configuration> <dependentWarIncludes>**/IncludeME,**/images</dependentWarIncludes> </configuration> </plugin> </plugins> ... </project>
<project> ... <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.1</version> <configuration> <dependentWarExcludes>WEB-INF/web.xml,index.*</dependentWarExcludes> </configuration> </plugin> </plugins> ... </project>
<project> ... <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.1</version> <configuration> <!-- default value is target/war/work --> <workDirectory>/tmp/extract_here</workDirectory> </configuration> </plugin> </plugins> ... </project>
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:
<project> ... <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <version>3.3.1</version> <configuration> <overlays> <overlay> <groupId>zipGroupId</groupId> <artifactId>zipArtifactId</artifactId> <type>zip</type> <targetPath>scripts</targetPath> </overlay> </overlays> </configuration> </plugin> </plugins> ... </project>