------
 Manipulating WAR Overlays
 ------
 Pete Marvin King
 ------
 28 June 2006
 
~~ Copyright 2006 The Apache Software Foundation.
~~
~~ Licensed 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/guides/mini/guide-apt-format.html

Manipulating WAR Overlays

 Normally all artifact dependencies are collected in <<<WEB-INF/lib>>> except
 for war artifacts. Instead, war artifacts are overlayed on the war source. 
 No configurations is necessary.
 
 To demonstrate, given a project structure
 
+-----------------+
 .
 |-- 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
+-----------------+

 which depends on <<<documentedprojectdependency-1.0-SNAPSHOT.war>>>.
 
+-----------------+
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
 |   |   |-- images-dependency
 |   |   |   `-- sampleimage.jpg
 |   |   |-- sampleresource
 |   |   |   `-- someresource-dependency.css
 |   |   `-- sampleresource-dependency
 |   |       `-- someresource-dependency.css
 |   `-- web.xml
 |-- index-dependency.jsp
 |-- jsp
 |   `-- websource-dependency.jsp
 `-- jsp-dependency
     `-- websource.jsp
+-----------------+

 Assuming that you've declared the war artifact as a dependency in your <<<pom.xml>>>.
 
+-----------------+
  [...]
    <dependencies>
      <dependency>
         <groupId>com.example.projects</groupId>
         <artifactId>documentedprojectdependency</artifactId>
         <version>1.0-SNAPSHOT</version>
         <type>war</type>
         <scope>runtime</scope>
      </dependency>
      [...]
    </dependencies>    
  [...]  
+-----------------+ 

 the resulting jar would end up like this
 
+-----------------+ 

 |-- META-INF
 |   |-- MANIFEST.MF
 |   `-- maven
 |       `-- com.example.projects
 |           |-- documentedproject
 |           |   |-- pom.properties
 |           |   `-- pom.xml
 |           `-- documentedprojectdependency
 |               |-- pom.properties
 |               `-- pom.xml
 |-- WEB-INF
 |   |-- classes
 |   |   |-- com
 |   |   |   `-- example
 |   |   |       `-- projects
 |   |   |           |-- SampleAction.class
 |   |   |           `-- SampleActionDependency.class
 |   |   |-- images
 |   |   |   |-- sampleimage-dependency.jpg
 |   |   |   `-- sampleimage.jpg
 |   |   |-- images-dependency
 |   |   |   `-- sampleimage.jpg
 |   |   |-- sampleresource
 |   |   |   `-- someresource-dependency.css
 |   |   `-- sampleresource-dependency
 |   |       `-- someresource-dependency.css
 |   `-- web.xml
 |-- index-dependency.jsp
 |-- index.jsp
 |-- jsp
 |   |-- websource-dependency.jsp
 |   `-- websource.jsp
 `-- jsp-dependency
     `-- websource.jsp
+-----------------+  
 
Configuring the war overlay

   The plugin parameters below can be used to modify the behaviour of the war overlay.
 
   *dependentWarIncludes - patterns used for matching files to be included from the war dependency.
   
+-----------------+  
  [...]
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.0</version>
        <configuration>
          <!-- default value is ** -->
          <dependentWarIncludes>**/IncludeME,**/images</dependentWarIncludes>   
        </configuration>
       </plugin>
    </plugins>  
  [...]
+-----------------+     
   
   *dependentWarExcludes - patterns used for matching files to be excluded from the war dependency.
   
+-----------------+  
  [...]
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.0</version>
        <configuration>
          <!-- no default value -->
          <dependentWarExcludes>WEB-INF/web.xml,index.*</dependentWarExcludes>   
        </configuration>
       </plugin>
    </plugins>  
  [...]
+-----------------+     

   
   *workDirectory - directory where the war files will be temporarily extracted.
   
+-----------------+  
  [...]
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.0</version>
        <configuration>
          <!-- default value is target/war/work -->
          <workDirectory>/tmp/extract_here</workDirectory>
        </configuration>
       </plugin>
    </plugins>  
  [...]
+-----------------+