Use the maven-war-plugin plugin to merge war packages

Reprinted from: http://jdonee.iteye.com/blog/794226

Pretty much http://maven.apache.org/plugins-archives/maven-war-plugin-2.1.1/overlays.html

http://maven.apache.org/plugins/maven-war-plugin/overlays.html

Translation of these two articles

When splitting a maven project in a large project, it is very likely that js, css, jsp and other files will be placed in different projects (modules divided according to business). Because if they are all concentrated in a maven webapp, then the webapp will be too large, and it will appear loose in business.

However, for these maven projects that hold js, css, and jsp, it is inappropriate if the packaging is set to jar, because it will be difficult for the periphery to read these internal files. In this scenario, a natural idea is to make a war package, and then combine multiple war packages in some way to get the final war package

This chapter introduces you to the Maven WAR Plugin's <overlays>, which you might call "overlays" or "overlays".

Overlays are mainly used to share common resources across multiple web projects. It can overwrite all files except native WAR artifacts in the target WAR itself, and collect the dependencies of native WAR projects in the WEB-INF/lib directory.

The following describes the functions of Overlays through some simple examples, including the types supported by Overlays, configuration, execution order in the packaging process, include/exclude files and global configuration, etc. Finally, it briefly explained how to overwrite the ZIP format file.

1. Overview of Overlays

In order to achieve the demonstration effect, we first set up a project structure named documentedproject in view of this:

The project depends on another WAR artifact – documentedprojectdependency-1.0-SNAPSHOT.war, of course you must declare it as a dependency of the current project under 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>
…

Next, we look at the structure of the documentedprojectdependency WAR file, which is roughly as follows:

documentedprojectdependency-1.0-SNAPSHOT.war

If nothing else, the target WAR will produce the following result:

It must be mentioned that the above web.xml file is from documentedproject.

2. Overlays support type

The WAR plugin can handle overwriting of artifacts in war and zip formats. However, to maintain backward compatibility, zip overrides are only processed if they are explicitly defined in the WAR plugin's configuration.

3, placement Overlays

In previous versions of the WAR plugin, configuration was not always necessary . If you feel that using the default settings satisfies your requirements, go ahead and do that. But if you need more control, then you'll want to take a good look at the section below.

The <overlay> element contains the following child elements:

id - overlay id. The WAR plugin will automatically generate one if you don't provide one.
groupId - configure the groupId you want to override.
artifactId - Configure the artifactId of the artifact you want to override.
type – Configure the type of widget you want to override. The default value is: war.
classifier - If there are multiple artifacts matching the current groupId/artifactId, then you need to configure the artifact's classifier to explicitly override (classifier: this element is used to help define some auxiliary artifacts for the build output).
includes - the files to include. By default, all files can be included.
excludes – files to exclude. By default, the META-INF directory is excluded.
targetPath - the target relative path in the webapp structure, of course this only works if the override type is war. By default, overridden content is appended under the webapp's root node.
skip - When set to true, skip this override. Default value is: false.

Having said so much, it is more intuitive to give an example.

For example, I want to exclude sampleimage-dependency.jpg under our documentedprojectdependency.war to overwrite the target war file:

…
<build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.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>
…

4. Packaging of Overlays

Overlays use a first-to-last policy (so if a file is overwritten by one copy, it will not be overwritten by another copy).

Overlays are applied in the order in which they are configured in <overlays>. If no configuration is specified, then their dependencies will be invoked in the order defined by the POM (warning: this has a lot of ambiguity, especially if you use transitive dependencies to override). If the current project uses a composite overlay (that is, it contains both configuration and non-configuration coverage), the non-configuration coverage is applied after the configuration coverage.

By default, the project source (aka the current build) follows the order in which dependencies are appended in the context of pom.xml (ie before any overriding elements have been applied). The current build defines a special override without groupId and artifactId. If overlays need to apply the first (first-pass first) principle, then simply configure the current build to follow these overlays.

For example, suppose my-webapp with groupid com.example.projects is a dependency of the current project, and you need to apply it first, as follows:

…
<build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.1</version>
        <configuration>
          <overlays>
            <overlay>
              <groupId>com.example.projects</groupId>
              <artifactId>my-webapp</artifactId>
            </overlay>
            <overlay>
              <!– 空 groupId/artifactId代表当前构建 –>
            </overlay>
          </overlays>
        </configuration>
      </plugin>
    </plugins>
</build>
…

Note: In the above case, other WAR dependencies not configured in the <overlays> element will be applied after the current build.

If you want to enforce a better and more granular coverage strategy, overlays can be multiplexed with different includes/exclude elements. For example, I want to use my-webapp's index.jsp override file in the current project, but my-webapp's other files are still controlled in the usual way. In view of this, we must define two override configurations for my-webapp:

…
<build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.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>            </overlay>
              <!– empty groupId/artifactId represents the current build –>

<!- If necessary, configure other overlays here -->

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

5. Overlay global settings

The following settings can specify global overlays and modify how all overlays are applied.

dependentWarIncludes - Set this include to default to apply to all overlays. Any overlay that does not specify an includes element will inherit this default setting.

    …
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.1</version>
        <configuration>
          <dependentWarIncludes>**/IncludeME,**/images</dependentWarIncludes>
        </configuration>
       </plugin>
    </plugins>
    …

dependentWarExcludes - Set this exclusion default to apply to all overlays. Overlays that do not specify the excludes element will inherit this default setting.

    …
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.1</version>
        <configuration>
          <dependentWarExcludes>WEB-INF/web.xml,index.*</dependentWarExcludes>
        </configuration>
       </plugin>
    </plugins>
    …

workDirectory – Sets the directory where overlays are temporarily extracted.

    …
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.1</version>
        <configuration>
          <!– default value is target/war/work –>
          <workDirectory>/tmp/extract_here</workDirectory>
        </configuration>
       </plugin>
    </plugins>
    …

useCache – When set to true, enables webapp schema caching. Default: false.

    …
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.1</version>
        <configuration>
          <useCache>true</useCache>
        </configuration>
       </plugin>
    </plugins>
    …

6. Overlay of ZIP dependencies

To make a zip dependency an override, you must specify it in the plugin configuration. For example, if you want to inject content through a zip overlay in the scripts directory of your web application, do the following:

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

Use the maven-war-plugin plugin to merge war packages

Guess you like