maven-war-plugin插件 overlays maven-war-plugin翻译

说明

翻译maven-war-plugin插件的部分内容

官方地址为：https://maven.apache.org/plugins/maven-war-plugin/index.html

---

Overview

概述

Introduction

介绍

Apache Maven WAR Plugin

apache maven war 插件

The WAR Plugin is responsible for collecting all artifact dependencies, classes and resources of the web application and packaging them into a web application archive.

war插件负责收集web工程中所有的依赖引用、class文件和资源文件，并将它们打包到一个web工程存档中

Goals Overview

目标概述

• war:war is the default goal invoked during the package phase for projects with a packaging type of war. It builds a WAR file.

• 当项目的打包类型为war时，war:war是一个默认的目标在package执行阶段被调用

• war:exploded is generally used to speed up testing during the developement phase by creating an exploded webapp in a specified directory.

• war:exploded用来在指定的目录下创建一个解包的webapp，这通常用来在开发阶段提升测试速度

• war:inplace another variation of war:explode where the webapp is instead generated in the web application source directory, which is src/main/webapp by default.

• war:inplace是war:explode的一个变体，会在web工程的源目录下创建webapp，默认的目录是src/main/webapp

Usage

用法

General instructions on how to use the WAR Plugin can be found on the usage page. Some more specific use cases are described in the examples given below. To share common resources across multiple web applications, see the documentation about using overlays.

关于如何使用war插件的整体介绍在usage页面可以找到。后面的examples中会给出一些更具体的使用案例。要在多个web工程中共享公共资源，请参阅有关使用overlays的文档

In case you still have questions regarding the plugin’s usage, please have a look at the FAQ and feel free to contact the user mailing list. The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the mail archive.

If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our issue tracker. When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our source repository and will find supplementary information in the guide to helping with Maven.

Goals

Plugin Documentation

Goals available for this plugin:

Goal	Description
war:exploded	Create an exploded webapp in a specified directory.
war:help	Display help information on maven-war-plugin. Call mvn war:help -Ddetail=true -Dgoal= to display parameter details.
war:inplace	Generate the webapp in the WAR source directory.
war:war	Build a WAR file.

System Requirements

The following specifies the minimum requirements to run this Maven plugin:

Maven	3.1.0
JDK	1.7
Memory	No minimum requirement.
Disk Space	No minimum requirement.

Usage

用法

You should specify the version in your project’s plugin configuration:

您应该明确指定项目中所使用插件的版本

<project>
    ...
    <build>
        <!-- To define the plugin version in your parent POM -->
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-war-plugin</artifactId>
                    <version>3.3.2</version>
                </plugin>
                ...
            </plugins>
        </pluginManagement>
        <!-- To use the plugin goals in your POM or parent POM -->
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.3.2</version>
            </plugin>
            ...
        </plugins>
    </build>
    ...
</project>

For more information, see “Guide to Configuring Plug-ins”

Usage

Usage

There are 4 ways to use the WAR Plugin:

• using the package phase with the project package type as war

• 当项目的打包方式为war包时，使用package阶段

• invocation of the war:war goal

• 调用war:war目标

• invocation of the war:exploded goal

• 调用war:exploded目标

• invocation of the war:inplace goal

• 调用war:inplace目标

Note: When using the war: goals it is assumed that the compile phase is already done. The WAR Plugin is not responsible for compiling the java sources or copying the resources.

注意：当使用war:目标时，假设compile阶段已经完成，war插件不负责编译源代码或者复制resources资源

To handle archiving this version of Maven WAR Plugin uses Maven Archiver 3.5.0.

To handle filtering this version of Maven WAR Plugin uses Maven Filtering 3.1.1.

Using the package phase with the project package type as war / invocation of the war:war goal

当项目的打包方式为war包时使用package阶段/调用war:war目标

This is the normal way of using the WAR Plugin. To illustrate, here’s the pom.xml for our project:

这是war插件的一般使用方式，为了说明，这是我们项目的pom文件

<project>
    ...
    <groupId>com.example.projects</groupId>
    <artifactId>documentedproject</artifactId>
    <packaging>war</packaging>
    <version>1.0-SNAPSHOT</version>
    <name>Documented Project</name>
    <url>http://example.com</url>
    ...
</project>

The project’s structure looks like this:

项目结构如下

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

Invoking

mvn package

or

mvn compile war:war

will generate the WAR file target/documentedproject-1.0-SNAPSHOT.war. Here are the contents of that WAR file:

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

Invocation of war:exploded goal

To speed up testing during the developement phase, war:explode can be used to generate the WAR in exploded form. Use the same project as above and invoke:

mvn compile war:exploded

This will generate an exploded version of the WAR in target/documentedproject-1.0-SNAPSHOT. The contents of that directory looks like this:

 documentedproject-1.0-SNAPSHOT
 |-- META-INF
 |-- WEB-INF
 |   |-- classes
 |   |   |-- com
 |   |   |   `-- example
 |   |   |       `-- projects
 |   |   |           `-- SampleAction.class
 |   |   `-- images
 |   |       `-- sampleimage.jpg
 |   `-- web.xml
 |-- index.jsp
 `-- jsp
     `-- websource.jsp

The default directory for the exploded WAR is target/<finalName>. The finalName is usually in the form of <artifactId>-<version>. This default directory can be overridden by specifying the webappDirectory parameter.

解包的war默认的目录是 target/，finalName通常采用-的形式，可以通过指定webappDirectory参数来覆盖此默认目录

<project>
    ...
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.3.2</version>
                <configuration>
                    <webappDirectory>/sample/servlet/container/deploy/directory</webappDirectory>
                </configuration>
            </plugin>
        </plugins>
    </build>
    ...
</project>

Invocation of war:inplace goal

Another variation of war:exploded is war:inplace. With war:inplace the exploded WAR is created in the webapp source, which defaults to src/main/webapp. Use our sample project above, and invoke:

mvn compile war:inplace

This will result in:

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

Configuration

Overlays

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用于跨多个web应用共享公共资源。除了要在war项目本身做叠加的组件，其它的依赖会被收集在WEB-INF/lib目录下

Overlays at a glance

To demonstrate, given this structure for the project documentedproject:

为了做演示，给出项目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:

项目依赖另一个war组件，documentedprojectdependency-1.0-SNAPSHOT.war，这个组件在pom.xml文件中，会被声明为一个dependency依赖

<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组件的结构如下

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.

上面的web.xml文件来自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.

war插件可以对wer或者zip组件做覆盖处理。然而，出于向后兼容的原因，只有在插件配置中明确指明了才会进行zip覆盖处理

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 element can have the following child elements:

overlay节点可以包含以下的子节点

• id - the id of the overlay. If none is provided, the WAR Plugin will generate one.

• id - overlay的id，如果没有，war插件将会生成一个。

• groupId - the groupId of the overlay artifact you want to configure.

• groupld - 想要配置的叠加组件的groupId

• artifactId - the artifactId of the overlay artifact you want to configure.

• artifactId - 想要配置的叠加组件的artifactId

• type - the type of the overlay artifact you want to configure. Default value is: war.

• type - 想要配置的叠加组件的type，默认是：war

• classifier - the classifier of the overlay artifact you want to configure if multiple artifacts matches the groupId/artifactId.

• classifier - 想要配置的叠加组件的classifier，如果多个组件匹配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.

• 要排除的文件，默认META-INF/MANIFEST.MF文件会被排除

• 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.

• targetPath - 目标在webapp结构中的相对路径，仅适用于war类型的覆盖。默认叠加的内容会被添加到webapp结构的根路径

• skip - set to true to skip this overlay. Default value is: false.

• skip - 设置为true可以跳过这个overlay，默认值为：false

• filtered - whether to apply filtering to this overlay. Default value is false.

• 是否对这个overlay进行过滤，默认值为：false

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

例如，叠加documentedprojectdependency.war组件并排除其中的sampleimage-dependency.jpg文件

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

叠加采用的是先赢策略（因此，如果一个文件被复制从一个叠加组件复制过来，就不会再从其它组件复制了），按照在overlays配置中定义的顺序进行加载。如果未提供相关的配置，加载的顺序为该依赖在pom文件中被应用的顺序（警告：这是不确定的，尤其当叠加为传递依赖时）。在混合情况下（例如，有配置的叠加和无配置的叠加），先加载有配置的叠加，再加载无配置的叠加

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.

默认情况下，项目的源代码（也就是当前构建的项目）会被优先加载（例如，在任何的叠加被加载之前），当前构建的项目被定义为一个没有groupId和artifactId的特殊的叠加，如果有一些叠加需要被首先应用，只需要配置当前构建的项目在这些叠加之后。

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:

举例，如果项目的一个依赖my-webapp,com.example.proects需要在项目自己的源代码之前被应用，请执行以下操作：

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

注意：在上面的场景中，任何其他WAR依赖项都将在当前构建之后应用，因为它们尚未在＜overlays＞元素中配置。

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:

为了执行更细粒度的覆盖策略，可以使用不同的包含/排除对叠加进行多次打包。例如，如果my-webapp中的index.jsp文件必须设置在webapp中，但其他文件可以用常规的方式控制，可以为my-webapp定义两个叠加配置：

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

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.

• dependentWarIncludes - 对所有的叠加设置默认的包含目录。默认情况下，任何没有指定includes元素的叠加都将继承此设置。

  <project>
      ...
      <plugins>
          <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-war-plugin</artifactId>
              <version>3.3.2</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.

• dependentWarExcludes - 对所有的叠加设置默认的排除目录。默认情况下，任何没有指定excludes元素的叠加都将继承此设置。

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

• workDirectory - sets the directory where overlays will be temporarily extracted.

• workDirectory - 设置临时提取叠加的目录

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

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:

要使用zip依赖作为叠加，您必须在插件的配置中明确配置它。例如，要在webapp的scripts目录中添加一个zip叠加的内容，请执行以下操作：

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