Chapter 14. Building a WAR
Abstract
This chapter describes how to build and package a WAR using Maven.
14.1. Modifying an Existing Maven Project
Overview
If you already have a Maven project and you want to modify it so that it generates a WAR, perform the following steps:
Change the package type to WAR
Configure Maven to generate a WAR by changing the package type to
war in your project's pom.xml file. Change the contents of the packaging element to war, as shown in the following example:
<project ... >
...
<packaging>war</packaging>
...
</project>
The effect of this setting is to select the Maven WAR plug-in,
maven-war-plugin, to perform packaging for this project.
Customize the JDK compiler version
It is almost always necessary to specify the JDK version in your POM file. If your code uses any modern features of the Java language—such as generics, static imports, and so on—and you have not customized the JDK version in the POM, Maven will fail to compile your source code. It is not sufficient to set the
JAVA_HOME and the PATH environment variables to the correct values for your JDK, you must also modify the POM file.
To configure your POM file, so that it accepts the Java language features introduced in JDK 1.6, add the following
maven-compiler-plugin plug-in settings to your POM (if they are not already present):
<project ... >
...
<build>
<defaultGoal>install</defaultGoal>
<plugins>
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.6</source>
<target>1.6</target>
</configuration>
</plugin>
</plugins>
</build>
...
</project>Store resources under webapp/WEB-INF
Resource files for the Web application are stored under the
/WEB-INF directory in the standard WAR directory layout. In order to ensure that these resources are copied into the root of the generated WAR package, store the WEB-INF directory under ProjectDir/src/main/webapp in the Maven directory tree, as follows:
ProjectDir/
pom.xml
src/
main/
webapp/
WEB-INF/
web.xml
classes/
lib/
In particular, note that the
web.xml file is stored at ProjectDir/src/main/webapp/WEB-INF/web.xml.
Customize the Maven WAR plug-in
It is possible to customize the Maven WAR plug-in by adding an entry to the
plugins section of the pom.xml file. Most of the configuration options are concerned with adding additonal resources to the WAR package. For example, to include all of the resources under the src/main/resources directory (specified relative to the location of pom.xml) in the WAR package, you could add the following WAR plug-in configuration to your POM:
<project ...>
...
<build>
...
<plugins>
<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>2.1.1</version>
<configuration>
<!-- Optionally specify where the web.xml file comes from -->
<webXml>src/main/webapp/WEB-INF/web.xml</webXml>
<!-- Optionally specify extra resources to include -->
<webResources>
<resource>
<directory>src/main/resources</directory>
<targetPath>WEB-INF</targetPath>
<includes>
<include>**/*</include>
</includes>
</resource>
</webResources>
</configuration>
</plugin>
...
</plugins>
</build>
</project>
The preceding plug-in configuration customizes the following settings:
webXml- Specifies where to find the
web.xmlfile in the current Maven project, relative to the location ofpom.xml. The default issrc/main/webapp/WEB-INF/web.xml. webResources- Specifies additional resource files that are to be included in the generated WAR package. It can contain the following sub-elements:
webResources/resource—each resource elements specifies a set of resource files to include in the WAR.webResources/resource/directory—specifies the base directory from which to copy resource files, where this directory is specified relative to the location ofpom.xml.webResources/resource/targetPath—specifies where to put the resource files in the generated WAR package.webResources/resource/includes—uses an Ant-style wildcard pattern to specify explicitly which resources should be included in the WAR.webResources/resource/excludes—uses an Ant-style wildcard pattern to specify explicitly which resources should be excluded from the WAR (exclusions have priority over inclusions).
For complete details of how to configure the Maven WAR plug-in, see http://maven.apache.org/plugins/maven-war-plugin/index.html.
Note
Do not use version 2.1 of the
maven-war-plugin plug-in, which has a bug that causes two copies of the web.xml file to be inserted into the generated .war file.
Building the WAR
To build the WAR defined by the Maven project, open a command prompt, go to the project directory (that is, the directory containing the
pom.xml file), and enter the following Maven command:
mvn install
The effect of this command is to compile all of the Java source files, to generate a WAR under the
ProjectDir/target directory, and then to install the generated WAR in the local Maven repository.
