Fixing MNG-623: "Improve the exclusion / inclusion of a dependency inside the

ear"
Committing on behalf of Stephane Nicoll.
Provides two new flags to customize ear modules: 

* excluded ; if set the module is not bundle in the EAR file 
* library ; if set the java module is considered as a 3rd party library and no
  entry is generated in the application.xml 
 
The patch also update the documentation.


git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@232833 13f79535-47bb-0310-9956-ffa450edef68

maven-plugins/maven-ear-plugin/src/main/java/org/apache/maven/plugin/ear/AbstractEarModule.java

@@ -47,6 +47,8 @@ public abstract class AbstractEarModule
 
     private String bundleFileName;
 
+    private Boolean excluded = Boolean.FALSE;
+
     /**
      * Empty constructor to be used when the module
      * is built based on the configuration.
@@ -179,6 +181,16 @@ public abstract class AbstractEarModule
         return bundleFileName;
     }
 
+    /**
+     * Specify whether this module should be excluded or not.
+     *
+     * @return true if this module should be skipped, false otherwise
+     */
+    public boolean isExcluded()
+    {
+        return excluded.booleanValue();
+    }
+
     public String toString()
     {
         StringBuffer sb = new StringBuffer();

maven-plugins/maven-ear-plugin/src/main/java/org/apache/maven/plugin/ear/AbstractEarMojo.java

@@ -23,7 +23,6 @@ import org.apache.maven.project.MavenProject;
 
 import java.io.File;
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Set;
@@ -66,6 +65,8 @@ public abstract class AbstractEarMojo
 
     private List earModules;
 
+    private List allModules;
+
     private File buildDir;
 
     public void execute()
@@ -73,9 +74,10 @@ public abstract class AbstractEarMojo
     {
         getLog().debug( "Resolving ear modules ..." );
 
+        allModules = new ArrayList();
+
         if ( modules != null && modules.length > 0 )
         {
-
             // Let's validate user-defined modules
             EarModule module = null;
             try
@@ -85,17 +87,13 @@ public abstract class AbstractEarMojo
                     module = (EarModule) modules[i];
                     getLog().debug( "Resolving ear module[" + module + "]" );
                     module.resolveArtifact( project.getArtifacts() );
+                    allModules.add( module );
                 }
             }
             catch ( EarPluginException e )
             {
                 throw new MojoExecutionException( "Failed to initialize ear modules", e );
             }
-            earModules = new ArrayList( Arrays.asList( modules ) );
-        }
-        else
-        {
-            earModules = new ArrayList();
         }
 
         // Let's add other modules
@@ -106,12 +104,26 @@ public abstract class AbstractEarMojo
 
             // Artifact is not yet registered and it has neither test, nor a
             // provided scope
-            if ( !isArtifactRegistered( artifact, earModules ) &&
+            if ( !isArtifactRegistered( artifact, allModules ) && !Artifact.SCOPE_TEST.equals( artifact.getScope() ) &&
-                 !Artifact.SCOPE_TEST.equals( artifact.getScope() ) &&
+                !Artifact.SCOPE_PROVIDED.equals( artifact.getScope() ) )
-                 !Artifact.SCOPE_PROVIDED.equals( artifact.getScope() ) )
             {
                 EarModule module = EarModuleFactory.newEarModule( artifact );
-                earModules.add( module );
+                allModules.add( module );
+            }
+        }
+
+        // Now we have everything let's built modules which have not been excluded
+        earModules = new ArrayList();
+        for ( Iterator iter = allModules.iterator(); iter.hasNext(); )
+        {
+            EarModule earModule = (EarModule) iter.next();
+            if ( earModule.isExcluded() )
+            {
+                getLog().debug( "Skipping ear module[" + earModule + "]" );
+            }
+            else
+            {
+                earModules.add( earModule );
             }
         }
 

maven-plugins/maven-ear-plugin/src/main/java/org/apache/maven/plugin/ear/EarModule.java

@@ -48,6 +48,13 @@ public interface EarModule
      */
     public String getUri();
 
+    /**
+     * Specify whether this module should be excluded or not.
+     *
+     * @return true if this module should be skipped, false otherwise
+     */
+    public boolean isExcluded();
+
     /**
      * Appends the <tt>XML</tt> representation of this module.
      *

maven-plugins/maven-ear-plugin/src/main/java/org/apache/maven/plugin/ear/JavaModule.java

@@ -30,6 +30,8 @@ public class JavaModule
 {
     protected static final String JAVA_MODULE = "java";
 
+    private Boolean library = Boolean.FALSE;
+
     public JavaModule()
     {
     }
@@ -41,15 +43,32 @@ public class JavaModule
 
     public void appendModule( XMLWriter writer, String version )
     {
-        writer.startElement( MODULE_ELEMENT );
+        // Generates an entry in the application.xml only if this
-        writer.startElement( JAVA_MODULE );
+        // module is not a library
-        writer.writeText( getUri() );
+        if (!isLibrary()) {
-        writer.endElement();
+            writer.startElement( MODULE_ELEMENT );
-        writer.endElement();
+            writer.startElement( JAVA_MODULE );
+            writer.writeText( getUri() );
+            writer.endElement();
+            writer.endElement();
+        }
     }
 
     protected String getType()
     {
         return "jar";
     }
+
+    /**
+     * Specify whether this Java module is a third party library or not.
+     * <p/>
+     * If <tt>true</tt>, the module will not be included in the generated
+     * <tt>application.xml</tt>.
+     *
+     * @return true if the module is a third party library, false otherwise
+     */
+    public boolean isLibrary()
+    {
+        return library.booleanValue();
+    }
 }

maven-plugins/maven-ear-plugin/src/site/apt/configuration-examples.apt

@@ -3,7 +3,7 @@
  ---
  Stéphane Nicoll
  ---
- 31-Jul-2005
+ 15-Aug-2005
  ---
 
 Introduction
@@ -22,6 +22,12 @@ Introduction
 
    * uri: the complete path in the EAR structure for the artifact
 
+  Also, a dependency might be excluded from the generated EAR file by specifying the
+  excluded flag.
+
+  Finally, third party libraries are handled by setting the library flag. If this flag
+  is set, the module is not included in the generated application.xml
+
 Customizing the context root
 
   The sample below shows how to customize the context root of an artifact to be placed
@@ -124,3 +130,56 @@ Customizing a module uri
     </plugins>
   </build>
 +---------
+
+Excluding a module
+
+  If for some reason a dependency which is declared in the pom of the project needs to be
+  excluded, the excluded flag could be used as follows:
+
++--------
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-ear-plugin</artifactId>
+        <configuration>
+           [...]
+           <modules>
+             <javaModule>
+               <groupId>artifactGroupId</groupId>
+               <artifactId>artifactId</artifactId>
+               <excluded>true</excluded>
+             </javaModule>
+          </modules>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
++---------
+
+Declaring a module as a third party library
+
+  If third party libraries need to be included in an EAR file, the 'library' flag could be
+  used. Note that no entry in the application.xml will be created for such module. This
+  flag works only for java modules.
+
++--------
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-ear-plugin</artifactId>
+        <configuration>
+           [...]
+           <modules>
+             <javaModule>
+               <groupId>artifactGroupId</groupId>
+               <artifactId>artifactId</artifactId>
+               <library>true</library>
+             </javaModule>
+          </modules>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
++---------