src/site/apt/overlays.apt.vm

 ------
 Overlays
 ------
 Pete Marvin King
 Stephane Nicoll
 Dennis Lundberg
 ------
 2010-08-14

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

Overlays

 Overlays are used to share common resources across multiple web applications.
 The dependencies of a WAR project are collected in <<<WEB-INF/lib>>>, except for WAR
 artifacts which are overlayed on the WAR project itself.


* Overlays at a glance

  To demonstrate, given this structure for the project <<<documentedproject>>>:

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

 The project depends on another WAR artifact, <<<documentedprojectdependency-1.0-SNAPSHOT.war>>>,
 which is declared as a dependency in the project's <<<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 structure for the <<<documentedprojectdependency>>> WAR file looks like this:

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

 The resulting WAR would end up like this:

+-----------------+
 |-- META-INF
 |   |-- MANIFEST.MF
 |   `-- maven
 |       `-- com.example.projects
 |           `-- documentedproject
 |               |-- 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
+-----------------+

  The <<<web.xml>>> file above comes from <<<documentedproject>>>.


* Overlay types

  The WAR Plugin handles both <<war>> and <<zip>> artifacts as overlays. However, for backward compatibility reasons, zip
  overlays are handled only if they are defined explicitly in the plugin's configuration.


* Configuring Overlays

  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!

  The <<<\<{overlay}\>>>> element can have the following child elements:

  * <<id>> - the id of the overlay. If none is provided, the WAR Plugin will
  generate one.

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

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

  * <<type>> - the type of the overlay artifact you want to
  configure. Default value is: <<<war>>>.

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

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

  * <<excludes>> - the files to exclude. By default, the <<<META-INF/MANIFEST.MF>>> file
  is excluded.

  * <<targetPath>> - the target relative path in the webapp structure, which is only
  available for overlays of type <<<war>>>. 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 value is: <<<false>>>.

  * <<filtered>> - whether to apply filtering to this overlay. Default value is <<<false>>>.

  []

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

+-----------------+
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <overlays>
            <overlay>
              <groupId>com.example.projects</groupId>
              <artifactId>documentedprojectdependency</artifactId>
              <excludes>
                <exclude>WEB-INF/classes/images/sampleimage-dependency.jpg</exclude>
              </excludes>
            </overlay>
          </overlays>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
+-----------------+


* Overlays packaging

  Overlays are applied with a first-win strategy (hence if a file has been copied by
  one overlay, it won't be copied by another). Overlays are applied in the order in which
  they are defined in the <<<\<overlays\>>>> configuration. If no configuration is provided,
  the order in which the dependencies are defined in the POM 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 applied 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 project's own source, do as follows:


+-----------------+
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <overlays>
            <overlay>
              <groupId>com.example.projects</groupId>
              <artifactId>my-webapp</artifactId>
            </overlay>
            <overlay>
              <!-- empty groupId/artifactId represents the current build -->
            </overlay>
          </overlays>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
+-----------------+

  <<Note:>> In the scenario above, any other WAR dependency will be applied after the current build
  since they have not been configured in the <<<\<overlays\>>>> element.

  To perform an even more 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 overlay configurations for <<<my-webapp>>>:

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


* Overlay global settings

   The following settings can be specified globally and modify the way all overlays are applied:

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

+-----------------+
    ...
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <!-- default value is target/war/work -->
          <workDirectory>/tmp/extract_here</workDirectory>
        </configuration>
       </plugin>
    </plugins>
    ...
+-----------------+

  * <<useCache>> - set to <<<true>>> to enable the webapp structure cache. Default value is: <<<false>>>.

+-----------------+
    ...
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <useCache>true</useCache>
        </configuration>
       </plugin>
    </plugins>
    ...
+-----------------+

* Zip dependencies with overlays

  To use a <<zip>> dependency as an overlay you have to configure it explicitly in the plugin'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>
        <version>${project.version}</version>
        <configuration>
          <overlays>
            <overlay>
              <groupId>zipGroupId</groupId>
              <artifactId>zipArtifactId</artifactId>
              <type>zip</type>
              <targetPath>scripts</targetPath>
            </overlay>
          </overlays>
        </configuration>
      </plugin>
    </plugins>
    ...
+-----------------+