Apache Maven WAR Plugin

Author:

1. Overview

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.

2. Plugin Goals

  • 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:exploded is generally used to speed up testing during the developement phase by creating an exploded webapp in a specified directory.
  • 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.

3. Usage

There are 4 ways to use the WAR Plugin:
  • using the package phase with the project package type as war
  • invocation of the war:war goal
  • invocation of the war:exploded goal
  • invocation of the war:inplace goal

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

This is the normal way of using the WAR Plugin. To illustrate, here's the pom.xml for our project:
<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

## 3.2 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/. The finalName is usually in the form of <artifactId>-. This default directory can be overridden by specifying the webappDirectory parameter.
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.2.2</version>
        <configuration>
          <webappDirectory>/sample/servlet/container/deploy/directory</webappDirectory>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

3.3 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

4. Examples

4.1 Adding web resources

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

4.2 Customizing manifest file

Generating a manifest classpath for a WAR is similar to for a JAR, but there are a couple of slight differences since you normally don't want a JAR in both the manifest classpath and the WEB-INF/lib directory. Customize the WAR Plugin's archiver:
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.2.2</version>
        <configuration>
          <archive>
            <manifest>
              <addClasspath>true</addClasspath>
            </manifest>
          </archive>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

4.3 Simple example

<plugin>
 <artifactId>maven-war-plugin</artifactId>
 <version>2.4</version>
 <configuration>
  <warSourceDirectory>WebContent</warSourceDirectory>
  <failOnMissingWebXml>false</failOnMissingWebXml>
 </configuration>
</plugin>

6. Conclusion

In this quick guide, we went over the war plugin and gave instructions on using and customizing it. Also we have seen the different plugin goals and their usage.

Comments

Post a Comment

Leave Comment