MNG-5387: Add ability to replace an artifact in mid-build

o change MavenProject#addArtifact to use the *last* version of a given artifact passed to it instead of the first.
o add comments.

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

maven-core/src/main/java/org/apache/maven/project/DefaultMavenProjectHelper.java

@@ -19,9 +19,6 @@ package org.apache.maven.project;
  * under the License.
  */
 
-import java.io.File;
-import java.util.List;
-
 import org.apache.maven.artifact.Artifact;
 import org.apache.maven.artifact.handler.ArtifactHandler;
 import org.apache.maven.artifact.handler.manager.ArtifactHandlerManager;
@@ -31,6 +28,9 @@ import org.codehaus.plexus.component.annotations.Component;
 import org.codehaus.plexus.component.annotations.Requirement;
 import org.codehaus.plexus.logging.AbstractLogEnabled;
 
+import java.io.File;
+import java.util.List;
+
 @SuppressWarnings( "deprecation" )
 @Component( role = MavenProjectHelper.class )
 public class DefaultMavenProjectHelper
@@ -90,20 +90,15 @@ public class DefaultMavenProjectHelper
         attachArtifact( project, artifact );
     }
 
+    /**
+     * Add an attached artifact or replace the file for an existing artifact.
+     * @see MavenProject#addAttachedArtifact(org.apache.maven.artifact.Artifact)
+     * @param project project reference.
+     * @param artifact artifact to add or replace.
+     */
     public void attachArtifact( MavenProject project, Artifact artifact )
     {
-        try
-        {
-            project.addAttachedArtifact( artifact );
-        }
-        catch ( DuplicateArtifactAttachmentException dae )
-        {
-            getLogger().warn( dae.getMessage() );
-
-            // We can throw this because it's unchecked, and won't change the MavenProjectHelper API, which would break
-            // backward compat if it did.
-            throw dae;
-        }
+        project.addAttachedArtifact( artifact );
     }
 
     public void addResource( MavenProject project, String resourceDirectory, List<String> includes, List<String> excludes )

maven-core/src/main/java/org/apache/maven/project/MavenProject.java

@@ -15,22 +15,6 @@ package org.apache.maven.project;
  * the License.
  */
 
-import java.io.File;
-import java.io.IOException;
-import java.io.Writer;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Collections;
-import java.util.HashMap;
-import java.util.HashSet;
-import java.util.Iterator;
-import java.util.LinkedHashMap;
-import java.util.LinkedHashSet;
-import java.util.List;
-import java.util.Map;
-import java.util.Properties;
-import java.util.Set;
-
 import org.apache.maven.RepositoryUtils;
 import org.apache.maven.artifact.Artifact;
 import org.apache.maven.artifact.ArtifactUtils;
@@ -75,6 +59,22 @@ import org.codehaus.plexus.util.xml.Xpp3Dom;
 import org.sonatype.aether.graph.DependencyFilter;
 import org.sonatype.aether.repository.RemoteRepository;
 
+import java.io.File;
+import java.io.IOException;
+import java.io.Writer;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Properties;
+import java.util.Set;
+
 /**
  * The concern of the project is provide runtime values based on the model.
  * <p/>
@@ -1449,19 +1449,46 @@ public class MavenProject
         return this.injectedProfileIds;
     }
 
+    private String logStringForArtifactFile( Artifact a )
+    {
+        if ( a.getFile() != null )
+        {
+            return a.getFile().getAbsolutePath();
+        }
+        else
+        {
+            return "(no path)";
+        }
+    }
+
+    /**
+     * Add or replace an artifact.
+     * In spite of the 'throws' declaration on this API, this method has never thrown an exception since Maven 3.0.x.
+     * Historically, it logged and ignored a second addition of the same g/a/v/c/t. Now it replaces the file for
+     * the artifact, so that plugins (e.g. shade) can change the pathname of the file for a particular set of
+     * coordinates.
+     * @param artifact the artifact to add or replace.
+     * @throws DuplicateArtifactAttachmentException
+     */
     public void addAttachedArtifact( Artifact artifact )
         throws DuplicateArtifactAttachmentException
     {
         List<Artifact> attachedArtifacts = getAttachedArtifacts();
-
-        if ( attachedArtifacts.contains( artifact ) )
+        for ( int ax = 0; ax < attachedArtifacts.size(); ax++ )
         {
-            if ( logger != null )
+            Artifact a = attachedArtifacts.get( ax );
+            if ( a.equals( artifact ))
             {
-                logger.warn( "Artifact " + artifact + " already attached to project, ignoring duplicate" );
+                if ( logger != null )
+                {
+                    logger.debug( String.format( "Replacing attached artifact %s. Old path %s, new path %s. ",
+                                                 a,
+                                                 logStringForArtifactFile( a ),
+                                                 logStringForArtifactFile( artifact ) ) );
+                }
+                attachedArtifacts.set( ax, artifact );
+                return;
             }
-            return;
-            //throw new DuplicateArtifactAttachmentException( this, artifact );
         }
 
         getAttachedArtifacts().add( artifact );

maven-core/src/main/java/org/apache/maven/project/MavenProjectHelper.java

@@ -22,18 +22,54 @@ package org.apache.maven.project;
 import java.io.File;
 import java.util.List;
 
+/**
+ * Convenience interface for plugins to add or replace artifacts and resources on projects.
+ */
 public interface MavenProjectHelper
 {
     String ROLE = MavenProjectHelper.class.getName();
 
+    /**
+     * See {@link #attachArtifact(MavenProject, String, String, java.io.File)}, but with type set to null.
+     * @param project project reference.
+     * @param artifactFile artifact file.
+     * @param artifactClassifier artifact classifier.
+     */
     void attachArtifact( MavenProject project, File artifactFile, String artifactClassifier );
 
+    /**
+     * * See {@link #attachArtifact(MavenProject, String, String, java.io.File)}, but with classifier set to null.
+     * @param project project reference.
+     * @param artifactType artifact type.
+     * @param artifactFile arrifact file.
+     */
     void attachArtifact( MavenProject project, String artifactType, File artifactFile );
 
+    /**
+     * Add or replace an artifact to the current project.
+     * @param project the project reference.
+     * @param artifactType the type (e.g. jar) or null.
+     * @param artifactClassifier the classifier or null.
+     * @param artifactFile the file for the artifact.
+     */
     void attachArtifact( MavenProject project, String artifactType, String artifactClassifier, File artifactFile );
 
+    /**
+     * Add a resource directory to the project.
+     * @param project project reference.
+     * @param resourceDirectory directory.
+     * @param includes include patterns.
+     * @param excludes exclude patterns.
+     */
     void addResource( MavenProject project, String resourceDirectory, List<String> includes, List<String> excludes );
 
+    /**
+     * Add a test resource directory to the project.
+     * @param project project reference.
+     * @param resourceDirectory directory.
+     * @param includes include patterns.
+     * @param excludes exclude patterns.
+     */
     void addTestResource( MavenProject project, String resourceDirectory, List<String> includes, List<String> excludes );
 
 }