------
 Overlays
 ------
 Pete Marvin King
 Stephane Nicoll
 ------
 12 Augustus 2007

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

Overlays

 Overlays are meant to share common resources accross multiple web applications. In general,
 all dependencies of a war project are collected in <<<WEB-INF/lib>>> except for war
 artifacts that are overlayed on the war source.

 In previous versions of the war plugin, no configuration was necessary. This is still the
 case if you are happy with the default settings. However, if you need more control, read on!

* Overlays at a glance

  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
 |   `-- web.xml
 |-- index-dependency.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 war 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
 |   `-- web.xml
 |-- index-dependency.jsp
 |-- index.jsp
 |-- jsp
 |   `-- websource.jsp
+-----------------+

* Overlay types

  The war plugin handles both <<war>> and <<zip>> artifacts. However, for backard compatibility reason, zip
  overlays are handled only if they are defined explicitely in the plugin's configuration.


* Configuring Overlays

  The {overlay} element can be configured as follows:

  * <<id>> - sets the id of the overlay. If none is provided, the war plugin will
  generate one.

  * <<groupId>> - sets the groupId of the overlay artifact you want to configure.

  * <<artifactId>> - sets the artifactId of the overlay artifact you want to
  configure.

  * <<classifier>> - sets the classifier of the overlay artifact you want to
  configure if multiple artifacts matches the groupId/artifact.

  * <<includes>> - sets the files to include. By default, all files are included.

  * <<excludes>> - sets the files to exclude. By default, the <<<META-INF>>> directory
  is excluded.

  * <<targetPath>> - sets the target relative path in the webapp structure, which is only
  available for <<war>> overlays. By default, the content of the overlay is added in the root
  structure of the webapp.

  * <<skip>> - set to true to skip this overlay. Default is false.

  For instance, to exclude the <<<sampleimage-dependency.jpg>>> of our
  <<<documentedprojectdependency>>> war overlay above:

+-----------------+
 [...]
   <plugins>
     <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-war-plugin</artifactId>
       <configuration>
         <overlays>
           <overlay>
             <groupId>com.example.projects</groupId>
             <artifactId>documentedprojectdependency</artifactId>
             <excludes>
               <exclude>images/sampleimage-dependency.jpg</exclude>
             </excludes>
           </overlay>
         </overlays>
       </configuration>
      </plugin>
   </plugins>
 [...]
+-----------------+


* Overlays packaging

  Overlays are applied with a first-win strategy (hence if a file has been copied by
  an overlay, it won't be copied anymore). Overlays are applied in the order in which
  they are defined in the <<<overlays>>> configuration. If no configuration is provided,
  the order in which they are defined in the dependencies is used (warning: this is not
  deterministic, especially if you have overlays as transitive dependencies). In case of
  a mixed situation (e.g. configured overlays and non)configured overlays), non-configured
  overlays are added after configured overlays.

  By default, the source of the project (<<<a.k.a>>> the current build) is added first (e.g.
  before any overlay is applied). The current build is defined as a special overlay
  with no <<<groupId>>>, <<<artifactId>>>. If overlays need to be applied first, simply
  configure the current build after those overlays.

  For instance, if <<<my-webapp>>> from the <<<com.example.projects>>> group is a dependency
  of the project and needs to be applied before the projec's source, do as follows:


+-----------------+
 [...]
   <plugins>
     <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-war-plugin</artifactId>
       <configuration>
         <overlays>
           <overlay>
             <groupId>com.example.projects</groupId>
             <artifactId>my-webapp</artifactId>
           </overlay>
           <overlay>
             <!-- empty groupId/artifactId detected as the current build -->
           </overlay>
         </overlays>
       </configuration>
      </plugin>
   </plugins>
 [...]
+-----------------+

  Note that in the scenario above, any other overlay will be applied afther the current build
  since they have not been configured in the <<<overlays>>> section.

  To perform an even fine grained overwriting policy, overlays can be packaged multiple times
  with different includes/excludes. For instance if the <<<index.jsp>>> file of the
  overlay <<<my-webapp>>> <<must>> be set in the webapp but other files can be controlled the
  regular way, define two overlays configuration for <<<my-webapp>>>:

+-----------------+
 [...]
   <plugins>
     <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-war-plugin</artifactId>
       <configuration>
         <overlays>
            <overlay>
              <id>my-webapp-index.jsp</id>
              <groupId>com.example.projects</groupId>
              <artifactId>my-webapp</artifactId>
              <includes>
                <include>index.jsp</include>
              </includes>
            </overlay>
            <overlay>
              <!-- empty groupId/artifactId detected as the current build -->
            </overlay>

            <!-- Other overlays here if necessary -->
            <overlay>
              <id>my-webapp</id>
              <groupId>com.example.projects</groupId>
              <artifactId>my-webapp</artifactId>
            </overlay>
          </overlays>
       </configuration>
      </plugin>
   </plugins>
 [...]
+-----------------+


* Overlay global settings

   The following settings can be specified globally and modify further the way overlays are applied.

   * <<dependentWarIncludes>> - sets the default includes to apply to all overlays. Any overlay that
    has no specific <<<includes>>> section inherit this settings by default.

+-----------------+
  [...]
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <dependentWarIncludes>**/IncludeME,**/images</dependentWarIncludes>
        </configuration>
       </plugin>
    </plugins>
  [...]
+-----------------+

   * <<dependentWarExcludes>> - sets the default excludes to apply to all overlays. Any overlay that
    has no specific <<<excludes>>> section inherit this settings by default.

+-----------------+
  [...]
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <dependentWarExcludes>WEB-INF/web.xml,index.*</dependentWarExcludes>
        </configuration>
       </plugin>
    </plugins>
  [...]
+-----------------+


   * <<workDirectory>> - sets the directory where overlays will be temporarily extracted.

+-----------------+
  [...]
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <!-- default value is target/war/work -->
          <workDirectory>/tmp/extract_here</workDirectory>
        </configuration>
       </plugin>
    </plugins>
  [...]
+-----------------+

  * <<useCache>> - set to false to disable the webapp structure cache. Default to true

+-----------------+
  [...]
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <useCache>false</useCache>
        </configuration>
       </plugin>
    </plugins>
  [...]
+-----------------+

* Zip dependencies with overlays

  To use a <<zip>> dependency as an overlay you have to configure it explicitely in the plugins's configuration. For
  instance to inject the content of a zip overlay in the <<scripts>> directory of the webapp, do as follows:

+-----------------+
 [...]
   <plugins>
     <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-war-plugin</artifactId>
       <configuration>
         <overlays>
            <overlay>
              <groupId>zipGroupId</groupId>
              <artifactId>zipArtifactId</artifactId>
              <targetPath>scripts</targetPath>
            </overlay>
          </overlays>
       </configuration>
      </plugin>
   </plugins>
 [...]
+-----------------+