src/site/apt/usage.apt.vm

 ------
 Usage
 ------
 Pete Marvin King
 ------
 2010-08-15
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

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

 []

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

 To handle archiving this version of Maven WAR Plugin uses
 {{{http://maven.apache.org/shared/maven-archiver/index.html}Maven Archiver}} ${mavenArchiverVersion}.

  To handle filtering this version of Maven WAR Plugin uses
  {{{http://maven.apache.org/shared/maven-filtering/index.html}Maven Filtering}} ${mavenFilteringVersion}.


*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
+----------+

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

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