maven war api 相关文档说明

war:war

Full name:

org.apache.maven.plugins:maven-war-plugin:2.5:war

Description:

Build a WAR file.

Attributes:

• Requires a Maven project to be executed.
• Requires dependency resolution of artifacts in scope: runtime.
• The goal is thread-safe and supports parallel builds.
• Binds by default to the lifecycle phase: package.

Required Parameters

Name	Type	Since	Description
cacheFile	File	2.1-alpha-1	The file containing the webapp structure cache. Default value is: ${project.build.directory}/war/work/webapp-cache.xml.
outputDirectory	String	-	The directory for the generated WAR. Default value is: ${project.build.directory}.
warName	String	-	The name of the generated WAR. Default value is: ${project.build.finalName}. User property is: war.warName.
warSourceDirectory	File	-	Single directory for extra files to include in the WAR. This is where you place your JSP files. Default value is: ${basedir}/src/main/webapp.
webappDirectory	File	-	The directory where the webapp is built. Default value is: ${project.build.directory}/${project.build.finalName}.
workDirectory	File	-	Directory to unpack dependent WARs into if needed. Default value is: ${project.build.directory}/war/work.

Optional Parameters

Name	Type	Since	Description
archive	MavenArchiveConfiguration	-	The archive configuration to use. See Maven Archiver Reference.
archiveClasses	boolean	2.0.1	Whether a JAR file will be created for the classes in the webapp. Using this optional configuration parameter will make the compiled classes to be archived into a JAR file and the classes directory will then be excluded from the webapp. Default value is: false. User property is: archiveClasses.
attachClasses	boolean	2.1-alpha-2	Whether classes (that is the content of the WEB-INF/classes directory) should be attached to the project as an additional artifact. By default the classifier for the additional artifact is 'classes'. You can change it with the<classesClassifier>someclassifier</classesClassifier> parameter. If this parameter true, another project can depend on the classes by writing something like: <dependency> <groupId>myGroup</groupId> <artifactId>myArtifact</artifactId> <version>myVersion</myVersion> <classifier>classes</classifier> </dependency> Default value is: false.
classesClassifier	String	2.1-alpha-2	The classifier to use for the attached classes artifact. Default value is: classes.
classifier	String	-	Classifier to add to the generated WAR. If given, the artifact will be an attachment instead. The classifier will not be applied to the JAR file of the project - only to the WAR file.
containerConfigXML	File	-	The path to a configuration file for the servlet container. Note that the file name may be different for different servlet containers. Apache Tomcat uses a configuration file named context.xml. The file will be copied to the META-INF directory. User property is: maven.war.containerConfigXML.
dependentWarExcludes	String	-	Deprecated. Use <overlay>/<excludes> instead
dependentWarIncludes	String	-	Deprecated. Use <overlay>/<includes> instead
escapeString	String	2.1-beta-1	Expression preceded with this String won't be interpolated. \${foo} will be replaced with ${foo}. User property is: maven.war.escapeString.
escapedBackslashesInFilePath	boolean	2.1-alpha-2	To escape interpolated values with Windows path c:\foo\bar will be replaced with c:\\foo\\bar. Default value is: false. User property is: maven.war.escapedBackslashesInFilePath.
failOnMissingWebXml	boolean	2.1-alpha-2	Whether or not to fail the build if the web.xml file is missing. Set to false if you want you WAR built without a web.xml file. This may be useful if you are building an overlay that has no web.xml file. Default value is: true. User property is: failOnMissingWebXml.
filteringDeploymentDescriptors	boolean	2.1-alpha-2	To filter deployment descriptors. Disabled by default. Default value is: false. User property is: maven.war.filteringDeploymentDescriptors.
filters	List	-	Filters (property files) to include during the interpolation of the pom.xml.
includeEmptyDirectories	boolean	2.4	(no description) Default value is: false.
nonFilteredFileExtensions	List	2.1-alpha-2	A list of file extensions that should not be filtered. Will be used when filtering webResources and overlays.
outputFileNameMapping	String	2.1-alpha-1	The file name mapping to use when copying libraries and TLDs. If no file mapping is set (default) the files are copied with their standard names.
overlays	List	2.1-alpha-1	The overlays to apply. Each <overlay> element may contain: id (defaults to currentBuild) groupId (if this and artifactId are null, then the current project is treated as its own overlay) artifactId (see above) classifier type includes (a list of string patterns) excludes (a list of string patterns) filtered (defaults to false) skip (defaults to false) targetPath (defaults to root of webapp structure)
packagingExcludes	String	2.1-alpha-2	The comma separated list of tokens to exclude from the WAR before packaging. This option may be used to implement the skinny WAR use case. Note that you can use the Java Regular Expressions engine to include and exclude specific pattern using the expression %regex[]. Hint: read the about (?!Pattern).
packagingIncludes	String	2.1-beta-1	The comma separated list of tokens to include in the WAR before packaging. By default everything is included. This option may be used to implement the skinny WAR use case. Note that you can use the Java Regular Expressions engine to include and exclude specific pattern using the expression %regex[].
primaryArtifact	boolean	-	Whether this is the main artifact being built. Set to false if you don't want to install or deploy it to the local repository instead of the default one in an execution. Default value is: true. User property is: primaryArtifact.
recompressZippedFiles	boolean	2.3	Indicates if zip archives (jar,zip etc) being added to the war should be compressed again. Compressing again can result in smaller archive size, but gives noticeably longer execution time. Default value is: true.
resourceEncoding	String	2.3	The encoding to use when copying filtered web resources. Default value is: ${project.build.sourceEncoding}. User property is: resourceEncoding.
supportMultiLineFiltering	boolean	2.4	Stop searching endToken at the end of line Default value is: false. User property is: maven.war.supportMultiLineFiltering.
useCache	boolean	2.1-alpha-1	Whether the cache should be used to save the status of the webapp across multiple runs. Experimental feature so disabled by default. Default value is: false. User property is: useCache.
useJvmChmod	boolean	2.4	use jvmChmod rather that cli chmod and forking process Default value is: true. User property is: maven.war.useJvmChmod.
warSourceExcludes	String	-	The comma separated list of tokens to exclude when copying the content of the warSourceDirectory.
warSourceIncludes	String	-	The comma separated list of tokens to include when copying the content of the warSourceDirectory. Default value is: **.
webResources	Resource[]	-	The list of webResources we want to transfer.
webXml	File	-	The path to the web.xml file to use. User property is: maven.war.webxml.

Parameter Details

archive:

The archive configuration to use. See  Maven Archiver Reference.

• Type: org.apache.maven.archiver.MavenArchiveConfiguration
• Required: No

---

archiveClasses:

Whether a JAR file will be created for the classes in the webapp. Using this optional configuration parameter will make the compiled classes to be archived into a JAR file and the classes directory will then be excluded from the webapp.

• Type: boolean
• Since: 2.0.1
• Required: No
• User Property: archiveClasses
• Default: false

---

attachClasses:

Whether classes (that is the content of the WEB-INF/classes directory) should be attached to the project as an additional artifact.

By default the classifier for the additional artifact is 'classes'. You can change it with the <classesClassifier>someclassifier</classesClassifier> parameter.

If this parameter true, another project can depend on the classes by writing something like:

<dependency>
  <groupId>myGroup</groupId>
  <artifactId>myArtifact</artifactId>
  <version>myVersion</myVersion>
  <classifier>classes</classifier>
</dependency>

• Type: boolean
• Since: 2.1-alpha-2
• Required: No
• Default: false

---

cacheFile:

The file containing the webapp structure cache.

• Type: java.io.File
• Since: 2.1-alpha-1
• Required: Yes
• Default: ${project.build.directory}/war/work/webapp-cache.xml

---

classesClassifier:

The classifier to use for the attached classes artifact.

• Type: java.lang.String
• Since: 2.1-alpha-2
• Required: No
• Default: classes

---

classifier:

Classifier to add to the generated WAR. If given, the artifact will be an attachment instead. The classifier will not be applied to the JAR file of the project - only to the WAR file.

• Type: java.lang.String
• Required: No

---

containerConfigXML:

The path to a configuration file for the servlet container. Note that the file name may be different for different servlet containers. Apache Tomcat uses a configuration file named context.xml. The file will be copied to the META-INF directory.

• Type: java.io.File
• Required: No
• User Property: maven.war.containerConfigXML

---

dependentWarExcludes:

Deprecated. Use <overlay>/<excludes> instead

The comma separated list of tokens to exclude when doing a WAR overlay.

• Type: java.lang.String
• Required: No

---

dependentWarIncludes:

Deprecated. Use <overlay>/<includes> instead

The comma separated list of tokens to include when doing a WAR overlay. Default is '**'

• Type: java.lang.String
• Required: No

---

escapeString:

Expression preceded with this String won't be interpolated.  \${foo} will be replaced with  ${foo}.

• Type: java.lang.String
• Since: 2.1-beta-1
• Required: No
• User Property: maven.war.escapeString

---

escapedBackslashesInFilePath:

To escape interpolated values with Windows path  c:\foo\bar will be replaced with  c:\\foo\\bar.

• Type: boolean
• Since: 2.1-alpha-2
• Required: No
• User Property: maven.war.escapedBackslashesInFilePath
• Default: false

---

failOnMissingWebXml:

Whether or not to fail the build if the  web.xml file is missing. Set to  false if you want you WAR built without a  web.xml file. This may be useful if you are building an overlay that has no web.xml file.

• Type: boolean
• Since: 2.1-alpha-2
• Required: No
• User Property: failOnMissingWebXml
• Default: true

---

filteringDeploymentDescriptors:

To filter deployment descriptors.  Disabled by default.

• Type: boolean
• Since: 2.1-alpha-2
• Required: No
• User Property: maven.war.filteringDeploymentDescriptors
• Default: false

---

filters:

Filters (property files) to include during the interpolation of the pom.xml.

• Type: java.util.List
• Required: No

---

includeEmptyDirectories:

(no description)

• Type: boolean
• Since: 2.4
• Required: No
• Default: false

---

nonFilteredFileExtensions:

A list of file extensions that should not be filtered.  Will be used when filtering webResources and overlays.

• Type: java.util.List
• Since: 2.1-alpha-2
• Required: No

---

outputDirectory:

The directory for the generated WAR.

• Type: java.lang.String
• Required: Yes
• Default: ${project.build.directory}

---

outputFileNameMapping:

The file name mapping to use when copying libraries and TLDs. If no file mapping is set (default) the files are copied with their standard names.

• Type: java.lang.String
• Since: 2.1-alpha-1
• Required: No

---

overlays:

The overlays to apply. Each <overlay> element may contain:

• id (defaults to currentBuild)
• groupId (if this and artifactId are null, then the current project is treated as its own overlay)
• artifactId (see above)
• classifier
• type
• includes (a list of string patterns)
• excludes (a list of string patterns)
• filtered (defaults to false)
• skip (defaults to false)
• targetPath (defaults to root of webapp structure)

• Type: java.util.List
• Since: 2.1-alpha-1
• Required: No

---

packagingExcludes:

The comma separated list of tokens to exclude from the WAR before packaging. This option may be used to implement the skinny WAR use case. Note that you can use the Java Regular Expressions engine to include and exclude specific pattern using the expression %regex[]. Hint: read the about (?!Pattern).

• Type: java.lang.String
• Since: 2.1-alpha-2
• Required: No

---

packagingIncludes:

The comma separated list of tokens to include in the WAR before packaging. By default everything is included. This option may be used to implement the skinny WAR use case. Note that you can use the Java Regular Expressions engine to include and exclude specific pattern using the expression %regex[].

• Type: java.lang.String
• Since: 2.1-beta-1
• Required: No

---

primaryArtifact:

Whether this is the main artifact being built. Set to  false if you don't want to install or deploy it to the local repository instead of the default one in an execution.

• Type: boolean
• Required: No
• User Property: primaryArtifact
• Default: true

---

recompressZippedFiles:

Indicates if zip archives (jar,zip etc) being added to the war should be compressed again. Compressing again can result in smaller archive size, but gives noticeably longer execution time.

• Type: boolean
• Since: 2.3
• Required: No
• Default: true

---

resourceEncoding:

The encoding to use when copying filtered web resources.

• Type: java.lang.String
• Since: 2.3
• Required: No
• User Property: resourceEncoding
• Default: ${project.build.sourceEncoding}

---

supportMultiLineFiltering:

Stop searching endToken at the end of line

• Type: boolean
• Since: 2.4
• Required: No
• User Property: maven.war.supportMultiLineFiltering
• Default: false

---

useCache:

Whether the cache should be used to save the status of the webapp across multiple runs. Experimental feature so disabled by default.

• Type: boolean
• Since: 2.1-alpha-1
• Required: No
• User Property: useCache
• Default: false

---

useJvmChmod:

use jvmChmod rather that cli chmod and forking process

• Type: boolean
• Since: 2.4
• Required: No
• User Property: maven.war.useJvmChmod
• Default: true

---

warName:

The name of the generated WAR.

• Type: java.lang.String
• Required: Yes
• User Property: war.warName
• Default: ${project.build.finalName}

---

warSourceDirectory:

Single directory for extra files to include in the WAR. This is where you place your JSP files.

• Type: java.io.File
• Required: Yes
• Default: ${basedir}/src/main/webapp

---

warSourceExcludes:

The comma separated list of tokens to exclude when copying the content of the warSourceDirectory.

• Type: java.lang.String
• Required: No

---

warSourceIncludes:

The comma separated list of tokens to include when copying the content of the warSourceDirectory.

• Type: java.lang.String
• Required: No
• Default: **

---

webResources:

The list of webResources we want to transfer.

• Type: org.apache.maven.model.Resource[]
• Required: No

---

webXml:

The path to the web.xml file to use.

• Type: java.io.File
• Required: No
• User Property: maven.war.webxml

---

webappDirectory:

The directory where the webapp is built.

• Type: java.io.File
• Required: Yes
• Default: ${project.build.directory}/${project.build.finalName}

---

workDirectory:

Directory to unpack dependent WARs into if needed.

• Type: java.io.File
• Required: Yes

• Default: ${project.build.directory}/war/work

----------------------------------------------------------------------------------------------\

Adding and Filtering External Web Resources

The default resource directory for all Maven projects is src/main/resources which will end up in target/classes and in WEB-INF/classes in the WAR. The directory structure will be preserved in the process.

The WAR Plugin is also capable of including resources not found in the default resource directory through the webResources parameter.

Adding web resources

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.5</version>
        <configuration>
          <webResources>
            <resource>
              <!-- this is relative to the pom.xml directory -->
              <directory>resource2</directory>
            </resource>
          </webResources>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

Using our sample project in the usage section with an added external resource, like this:

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

would end up in the WAR as:

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
 |-- external-resource.jpg
 |-- image2
 |   `-- external-resource2.jpg
 |-- index.jsp
 `-- jsp
     `-- websource.jsp

external-resource2.jpg and image2 are copied to the root of the WAR, preserving the directory structure.

Configuring web Resources

webResources is a list of resources. All options of resource are supported.

A web resource

• can have includes/excludes
• can be filtered
• is not limited to the default destination - the root of the WAR

Includes/Excludes

To include all jpgs in the WAR we can add the following to our POM configuration from above:

        ...
        <configuration>
          <webResources>
            <resource>
              <!-- this is relative to the pom.xml directory -->
              <directory>resource2</directory>
              <!-- the list has a default value of ** -->
              <includes>
                <include>**/*.jpg</include>
              </includes>
            </resource>
          </webResources>
        </configuration>
        ...

To exclude the image2 directory from the WAR add this:

        ...
        <configuration>
          <webResources>
            <resource>
              <!-- this is relative to the pom.xml directory -->
              <directory>resource2</directory>
              <!-- there's no default value for this -->
              <excludes>
                <exclude>**/image2</exclude>
              </excludes>
            </resource>
          </webResources>
        </configuration>
        ...

Be careful when mixing includes and excludes, excludes will have a higher priority. Includes can not override excludes if a resource matches both.

Having this configuration will exclude all jpgs from the WAR:

        ...
        <configuration>
          <webResources>
            <resource>
              <!-- this is relative to the pom.xml directory -->
              <directory>resource2/</directory>
              <!-- the list has a default value of ** -->
              <includes>
                <include>image2/*.jpg</include>
              </includes>
              <!-- there's no default value for this -->
              <excludes>
                <exclude>**/*.jpg</exclude>
              </excludes>
            </resource>
          </webResources>
        </configuration>
        ...

Here's another example of how to specify include and exclude patterns:

        ...
        <configuration>
          <webResources>
            <resource>
              <!-- this is relative to the pom.xml directory -->
              <directory>resource2</directory>
              <!-- the default value is ** -->
              <includes>
                <include>**/pattern1</include>
                <include>*pattern2</include>
              </includes>
              <!-- there's no default value for this -->
              <excludes>
                <exclude>*pattern3/pattern3</exclude>
                <exclude>pattern4/pattern4</exclude>
              </excludes>
            </resource>
          </webResources>
        </configuration>
        ...

Filtering

Using our example above, we can also configure filters for our resources. We will add a hypothetical configurations directory to our project:

 .
 |-- configurations
 |   |-- config.cfg
 |   `-- properties
 |       `-- config.prop
 |-- pom.xml
 |-- resource2
 |   |-- external-resource.jpg
 |   `-- image2
 |       `-- external-resource2.jpg
 `-- src
     `-- main
         |-- java
         |   `-- com
         |       `-- example
         |           `-- projects
         |               `-- SampleAction.java
         |-- resources
         |   `-- images
         |       `-- sampleimage.jpg
         `-- webapp
             |-- WEB-INF
             |   `-- web.xml
             |-- index.jsp
             `-- jsp
                 `-- websource.jsp

To prevent corrupting your binary files when filtering is enabled, you can configure a list of file extensions that will not be filtered.

        ...
        <configuration>
          <!-- the default value is the filter list under build -->
          <!-- specifying a filter will override the filter list under build -->
          <filters>
            <filter>properties/config.prop</filter>
          </filters>
          <nonFilteredFileExtensions>
            <!-- default value contains jpg,jpeg,gif,bmp,png -->
            <nonFilteredFileExtension>pdf</nonFilteredFileExtension>
          </nonFilteredFileExtensions>
          <webResources>
            <resource>
              <directory>resource2</directory>
              <!-- it's not a good idea to filter binary files -->
              <filtering>false</filtering>
            </resource>
            <resource>
              <directory>configurations</directory>
              <!-- enable filtering -->
              <filtering>true</filtering>
              <excludes>
                <exclude>**/properties</exclude>
              </excludes>
            </resource>
          </webResources>
        </configuration>
        ...

config.prop

interpolated_property=some_config_value

config.cfg

<another_ioc_container>
   <configuration>${interpolated_property}</configuration>
</another_ioc_container>

The resulting WAR would be:

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
 |-- config.cfg
 |-- external-resource.jpg
 |-- image2
 |   `-- external-resource2.jpg
 |-- index.jsp
 `-- jsp
     `-- websource.jsp

and the content of config.cfg would be:

<another_ioc_container>
   <configuration>some_config_value</configuration>
</another_ioc_container>

Note: In versions 2.2 and earlier of this plugin the platform encoding was used when filtering resources. Depending on what that encoding was you could end up with scrambled characters after filtering. Starting with version 2.3 this plugin respects the property project.build.sourceEncoding when filtering resources. One notable exception to this is that .xml files are filtered using the encoding specified inside the xml-file itself.

Overriding the default destination directory

By default web resources are copied to the root of the WAR, as shown in the previous example. To override the default destination directory, specify the target path.

        ...
        <configuration>
          <webResources>
            <resource>
              ...
            </resource>
            <resource>
              <directory>configurations</directory>
              <!-- override the destination directory for this resource -->
              <targetPath>WEB-INF</targetPath>
              <!-- enable filtering -->
              <filtering>true</filtering>
              <excludes>
                <exclude>**/properties</exclude>
              </excludes>
            </resource>
          </webResources>
        </configuration>
        ...

Using the sample project the resulting WAR would look like this:

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
 |   |-- config.cfg
 |   `-- web.xml
 |-- external-resource.jpg
 |-- image2
 |   `-- external-resource2.jpg
 |-- index.jsp
 `-- jsp
     `-- websource.jsp

http://maven.apache.org/plugins/maven-war-plugin/examples/adding-filtering-webresources.html