You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sn...@apache.org on 2007/08/12 11:56:51 UTC
svn commit: r565031 - in /maven/plugins/branches/MWAR-97-2/src:
main/java/org/apache/maven/plugin/war/
main/java/org/apache/maven/plugin/war/overlay/ site/ site/apt/
site/apt/examples/ test/java/org/apache/maven/plugin/war/overlay/
Author: snicoll
Date: Sun Aug 12 02:56:50 2007
New Revision: 565031
URL: http://svn.apache.org/viewvc?view=rev&rev=565031
Log:
- Default overlay exclude is now META-INF/MANIFEST.MF
- Added documentation
Added:
maven/plugins/branches/MWAR-97-2/src/site/apt/overlays.apt
Removed:
maven/plugins/branches/MWAR-97-2/src/site/apt/examples/war-overlay.apt
Modified:
maven/plugins/branches/MWAR-97-2/src/main/java/org/apache/maven/plugin/war/Overlay.java
maven/plugins/branches/MWAR-97-2/src/main/java/org/apache/maven/plugin/war/overlay/OverlayManager.java
maven/plugins/branches/MWAR-97-2/src/site/apt/index.apt
maven/plugins/branches/MWAR-97-2/src/site/site.xml
maven/plugins/branches/MWAR-97-2/src/test/java/org/apache/maven/plugin/war/overlay/OverlayManagerTest.java
Modified: maven/plugins/branches/MWAR-97-2/src/main/java/org/apache/maven/plugin/war/Overlay.java
URL: http://svn.apache.org/viewvc/maven/plugins/branches/MWAR-97-2/src/main/java/org/apache/maven/plugin/war/Overlay.java?view=diff&rev=565031&r1=565030&r2=565031
==============================================================================
--- maven/plugins/branches/MWAR-97-2/src/main/java/org/apache/maven/plugin/war/Overlay.java (original)
+++ maven/plugins/branches/MWAR-97-2/src/main/java/org/apache/maven/plugin/war/Overlay.java Sun Aug 12 02:56:50 2007
@@ -44,7 +44,7 @@
public static final String[] DEFAULT_INCLUDES = new String[]{"**/**"};
- public static final String[] DEFAULT_EXCLUDES = new String[]{"META-INF/**"};
+ public static final String[] DEFAULT_EXCLUDES = new String[]{"META-INF/MANIFEST.MF"};
private static Overlay currentProjectInstance;
Modified: maven/plugins/branches/MWAR-97-2/src/main/java/org/apache/maven/plugin/war/overlay/OverlayManager.java
URL: http://svn.apache.org/viewvc/maven/plugins/branches/MWAR-97-2/src/main/java/org/apache/maven/plugin/war/overlay/OverlayManager.java?view=diff&rev=565031&r1=565030&r2=565031
==============================================================================
--- maven/plugins/branches/MWAR-97-2/src/main/java/org/apache/maven/plugin/war/overlay/OverlayManager.java (original)
+++ maven/plugins/branches/MWAR-97-2/src/main/java/org/apache/maven/plugin/war/overlay/OverlayManager.java Sun Aug 12 02:56:50 2007
@@ -202,10 +202,10 @@
return null;
}
- // TODO this might not always return the artifacts in the right order. Hence some tests might fail
final Iterator it = warArtifacts.iterator();
while ( it.hasNext() )
{
+ // TODO Handle ZIP artifact ; Handle classifier dependencies properly (clash management)
Artifact artifact = (Artifact) it.next();
if ( overlay.getGroupId().equals( artifact.getGroupId() ) &&
overlay.getArtifactId().equals( artifact.getArtifactId() ) &&
Modified: maven/plugins/branches/MWAR-97-2/src/site/apt/index.apt
URL: http://svn.apache.org/viewvc/maven/plugins/branches/MWAR-97-2/src/site/apt/index.apt?view=diff&rev=565031&r1=565030&r2=565031
==============================================================================
--- maven/plugins/branches/MWAR-97-2/src/site/apt/index.apt (original)
+++ maven/plugins/branches/MWAR-97-2/src/site/apt/index.apt Sun Aug 12 02:56:50 2007
@@ -40,7 +40,8 @@
* Usage
- Instructions on how to use the Maven WAR Plugin can be found {{{usage.html}here}}.
+ Instructions on how to use the Maven WAR Plugin can be found {{{usage.html}here}}. Specific documentation
+ regarding overlays can be found {{{overlays.html}here}}
* Examples
@@ -48,8 +49,6 @@
you can take a look into the following examples:
* {{{examples/adding-filtering-webresources.html}Adding and Filtering External Web Resources}}
-
- * {{{examples/war-overlay.html}Manipulating WAR Overlays}}
* {{{examples/war-manifest-guide.html}War Manifest Customization}}
Added: maven/plugins/branches/MWAR-97-2/src/site/apt/overlays.apt
URL: http://svn.apache.org/viewvc/maven/plugins/branches/MWAR-97-2/src/site/apt/overlays.apt?view=auto&rev=565031
==============================================================================
--- maven/plugins/branches/MWAR-97-2/src/site/apt/overlays.apt (added)
+++ maven/plugins/branches/MWAR-97-2/src/site/apt/overlays.apt Sun Aug 12 02:56:50 2007
@@ -0,0 +1,336 @@
+ ------
+ 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
++-----------------+
+
+
+* 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/MANIFEST.MF>>>
+ is excluded.
+
+ * <<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>
+ [...]
++-----------------+
+
+
Modified: maven/plugins/branches/MWAR-97-2/src/site/site.xml
URL: http://svn.apache.org/viewvc/maven/plugins/branches/MWAR-97-2/src/site/site.xml?view=diff&rev=565031&r1=565030&r2=565031
==============================================================================
--- maven/plugins/branches/MWAR-97-2/src/site/site.xml (original)
+++ maven/plugins/branches/MWAR-97-2/src/site/site.xml Sun Aug 12 02:56:50 2007
@@ -27,9 +27,11 @@
<item name="Usage" href="usage.html"/>
<item name="FAQ" href="faq.html"/>
</menu>
+ <menu name="Configuration">
+ <item name="Overlays" href="overlays.html"/>
+ </menu>
<menu name="Examples">
- <item name="Adding and Filtering External Web Resources" href="examples/adding-filtering-webresources.html"/>
- <item name="Manipulating WAR Overlays" href="examples/war-overlay.html"/>
+ <item name="Adding and Filtering External Web Resources" href="examples/adding-filtering-webresources.html"/>
<item name="War Manifest Customization" href="examples/war-manifest-guide.html"/>
<item name="Rapid Testing Using Jetty6" href="examples/rapid-testing-jetty6-plugin.html"/>
<item name="Creating Skinny WARs" href="examples/skinny-wars.html"/>
Modified: maven/plugins/branches/MWAR-97-2/src/test/java/org/apache/maven/plugin/war/overlay/OverlayManagerTest.java
URL: http://svn.apache.org/viewvc/maven/plugins/branches/MWAR-97-2/src/test/java/org/apache/maven/plugin/war/overlay/OverlayManagerTest.java?view=diff&rev=565031&r1=565030&r2=565031
==============================================================================
--- maven/plugins/branches/MWAR-97-2/src/test/java/org/apache/maven/plugin/war/overlay/OverlayManagerTest.java (original)
+++ maven/plugins/branches/MWAR-97-2/src/test/java/org/apache/maven/plugin/war/overlay/OverlayManagerTest.java Sun Aug 12 02:56:50 2007
@@ -35,6 +35,10 @@
extends PlexusTestCase
{
+ public static final String DEFAULT_INCLUDES = "**/**";
+
+ public static final String DEFAULT_EXCLUDES = "META-INF/MANIFEST.MF";
+
public void testEmptyProject()
throws Exception
@@ -43,7 +47,7 @@
final List overlays = new ArrayList();
try
{
- OverlayManager manager = new OverlayManager( overlays, project, "**/**", "META-INF/**" );
+ OverlayManager manager = new OverlayManager( overlays, project, DEFAULT_INCLUDES, DEFAULT_EXCLUDES );
assertNotNull( manager.getOverlays() );
assertEquals( 1, manager.getOverlays().size() );
assertEquals( Overlay.currentProjectInstance(), manager.getOverlays().get( 0 ) );
@@ -67,7 +71,7 @@
try
{
- OverlayManager manager = new OverlayManager( overlays, project, "**/**", "META-INF/**" );
+ OverlayManager manager = new OverlayManager( overlays, project, DEFAULT_INCLUDES, DEFAULT_EXCLUDES );
assertNotNull( manager.getOverlays() );
assertEquals( 2, manager.getOverlays().size() );
assertEquals( Overlay.currentProjectInstance(), manager.getOverlays().get( 0 ) );
@@ -93,7 +97,7 @@
try
{
- OverlayManager manager = new OverlayManager( overlays, project, "**/**", "META-INF/**" );
+ OverlayManager manager = new OverlayManager( overlays, project, DEFAULT_INCLUDES, DEFAULT_EXCLUDES );
assertNotNull( manager.getOverlays() );
assertEquals( 2, manager.getOverlays().size() );
assertEquals( Overlay.currentProjectInstance(), manager.getOverlays().get( 0 ) );
@@ -119,7 +123,7 @@
try
{
- new OverlayManager( overlays, project, "**/**", "META-INF/**" );
+ new OverlayManager( overlays, project, DEFAULT_INCLUDES, DEFAULT_EXCLUDES );
fail( "Should have failed to validate an unknown overlay" );
}
catch ( InvalidOverlayConfigurationException e )
@@ -144,7 +148,7 @@
try
{
- OverlayManager manager = new OverlayManager( overlays, project, "**/**", "META-INF/**" );
+ OverlayManager manager = new OverlayManager( overlays, project, DEFAULT_INCLUDES, DEFAULT_EXCLUDES );
assertNotNull( manager.getOverlays() );
assertEquals( 3, manager.getOverlays().size() );
assertEquals( overlays.get( 0 ), manager.getOverlays().get( 0 ) );