| ------ |
| 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. |
| |
| * <<dependentWarIncludes>> - sets the default includes to apply to all overlays. Any overlay that |
| has no specific <<<includes>>> element will inherit this setting by default. |
| |
| +-----------------+ |
| ... |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-war-plugin</artifactId> |
| <version>${project.version}</version> |
| <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>>> element will inherit this setting by default. |
| |
| +-----------------+ |
| ... |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-war-plugin</artifactId> |
| <version>${project.version}</version> |
| <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> |
| <version>${project.version}</version> |
| <configuration> |
| <!-- default value is target/war/work --> |
| <workDirectory>/tmp/extract_here</workDirectory> |
| </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> |
| ... |
| +-----------------+ |