【Maven】：文件资源共享（Overlay）
目录
1. 背景
2. 机制
2.1. Overlays at a glance
2.2. Overlay types
2.3. Configuring Overlays
2.4. Overlays packaging1. 背景
- 技术栈
- 依赖管理：Maven
- 研发技术：jQuery + JSP + Spring
- 发布方式：WAR 包
- 打包工具：maven-war-plugin
- 原因
- 实现项目间文件资源共享（JSP、JS、CSS、PNG、HTML 等）
- 解决方案
- maven-war-plugin 的 Overlays 技术
2. 机制（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.
2.1. 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.jspThe project documentedproject 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>
</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.jspThe 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.jspThe web.xml file above comes from documentedproject.
2.2. 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.
2.3. 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:
<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>2.4. 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:
<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>2.5. Overlay global settings
The following settings can be specified globally and modify the way all overlays are applied.
- dependentWarIncludes - sets the default includes to apply to all overlays. Any overlay that has no specific includes element will inherit this setting by default.
<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>- dependentWarExcludes - sets the default excludes to apply to all overlays. Any overlay that has no specific excludes element will inherit this setting by default.
<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>- workDirectory - sets the directory where overlays will be temporarily extracted.
<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>参考：
Overlays： http://maven.apache.org/plugins/maven-war-plugin/overlays.html
