PR: MNG-145

Implement and document repository download mirrors

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

maven-artifact/src/main/java/org/apache/maven/artifact/manager/DefaultWagonManager.java

@@ -33,6 +33,7 @@ import org.apache.maven.wagon.authorization.AuthorizationException;
 import org.apache.maven.wagon.events.TransferListener;
 import org.apache.maven.wagon.observers.ChecksumObserver;
 import org.apache.maven.wagon.proxy.ProxyInfo;
+import org.apache.maven.wagon.repository.Repository;
 import org.codehaus.plexus.PlexusConstants;
 import org.codehaus.plexus.PlexusContainer;
 import org.codehaus.plexus.component.repository.exception.ComponentLifecycleException;
@@ -57,11 +58,14 @@ public class DefaultWagonManager
 {
     private PlexusContainer container;
 
-    // TODO: proxies and authentication are via settings, and should come in via an alternate method - perhaps attached to ArtifactRepository before the method is called (so AR would be composed of WR, not inherit it)
+    // TODO: proxies, authentication and mirrors are via settings, and should come in via an alternate method - perhaps
+    // attached to ArtifactRepository before the method is called (so AR would be composed of WR, not inherit it)
     private Map proxies = new HashMap();
 
     private Map authenticationInfoMap = new HashMap();
 
+    private Map mirrors = new HashMap();
+
     private TransferListener downloadMonitor;
 
     private ArtifactHandlerManager artifactHandlerManager;
@@ -115,10 +119,12 @@ public class DefaultWagonManager
                                 TransferListener downloadMonitor )
         throws TransferFailedException
     {
+        String protocol = repository.getProtocol();
+
         Wagon wagon = null;
         try
         {
-            wagon = getWagon( repository.getProtocol() );
+            wagon = getWagon( protocol );
         }
         catch ( UnsupportedProtocolException e )
         {
@@ -149,8 +155,7 @@ public class DefaultWagonManager
 
         try
         {
-            wagon.connect( repository, getAuthenticationInfo( repository.getId() ),
+            wagon.connect( repository, getAuthenticationInfo( repository.getId() ), getProxy( protocol ) );
-                           getProxy( repository.getProtocol() ) );
 
             wagon.put( source, remotePath );
 
@@ -271,9 +276,10 @@ public class DefaultWagonManager
 
         Wagon wagon;
 
+        String protocol = repository.getProtocol();
         try
         {
-            wagon = getWagon( repository.getProtocol() );
+            wagon = getWagon( protocol );
         }
         catch ( UnsupportedProtocolException e )
         {
@@ -308,8 +314,13 @@ public class DefaultWagonManager
 
         try
         {
-            wagon.connect( repository, getAuthenticationInfo( repository.getId() ),
+            Repository mirror = getMirror( repository.getId() );
-                           getProxy( repository.getProtocol() ) );
+            if ( mirror != null )
+            {
+                repository = repository.createMirror( mirror );
+            }
+
+            wagon.connect( repository, getAuthenticationInfo( repository.getId() ), getProxy( protocol ) );
 
             wagon.get( remotePath, temp );
 
@@ -421,6 +432,11 @@ public class DefaultWagonManager
         return (AuthenticationInfo) authenticationInfoMap.get( id );
     }
 
+    private Repository getMirror( String mirrorOf )
+    {
+        return (Repository) mirrors.get( mirrorOf );
+    }
+
     /**
      * Set the proxy used for a particular protocol.
      *
@@ -476,4 +492,11 @@ public class DefaultWagonManager
 
         authenticationInfoMap.put( repositoryId, authInfo );
     }
+
+    public void addMirror( String id, String mirrorOf, String url )
+    {
+        Repository mirror = new Repository( id, url );
+
+        mirrors.put( mirrorOf, mirror );
+    }
 }

maven-artifact/src/main/java/org/apache/maven/artifact/manager/WagonManager.java

@@ -59,5 +59,7 @@ public interface WagonManager
     void addAuthenticationInfo( String repositoryId, String username, String password, String privateKey,
                                 String passphrase );
 
+    void addMirror( String id, String mirrorOf, String url );
+
     void setDownloadMonitor( TransferListener downloadMonitor );
 }

maven-artifact/src/main/java/org/apache/maven/artifact/repository/ArtifactRepository.java

@@ -75,4 +75,9 @@ public class ArtifactRepository
     {
         return snapshotPolicy;
     }
+
+    public ArtifactRepository createMirror( Repository mirror )
+    {
+        return new ArtifactRepository( mirror.getId(), mirror.getUrl(), layout, snapshotPolicy );
+    }
 }

maven-core/src/main/java/org/apache/maven/DefaultMaven.java

@@ -36,6 +36,7 @@ import org.apache.maven.reactor.ReactorException;
 import org.apache.maven.settings.Proxy;
 import org.apache.maven.settings.Server;
 import org.apache.maven.settings.Settings;
+import org.apache.maven.settings.Mirror;
 import org.codehaus.plexus.PlexusConstants;
 import org.codehaus.plexus.PlexusContainer;
 import org.codehaus.plexus.component.repository.exception.ComponentLookupException;
@@ -87,6 +88,15 @@ public class DefaultMaven
             getLogger().info( "Maven is running in offline mode." );
         }
 
+        try
+        {
+            resolveParameters( request.getSettings() );
+        }
+        catch ( ComponentLookupException e )
+        {
+            throw new ReactorException( "Unable to configure Maven for execution", e );
+        }
+
         EventDispatcher dispatcher = request.getEventDispatcher();
         String event = MavenEvents.REACTOR_EXECUTION;
 
@@ -200,15 +210,6 @@ public class DefaultMaven
 
         MavenSession session = createSession( request, project );
 
-        try
-        {
-            resolveParameters( request );
-        }
-        catch ( ComponentLookupException e )
-        {
-            throw new LifecycleExecutionException( "Unable to configure Maven for execution", e );
-        }
-
         // !! This is ripe for refactoring to an aspect.
         // Event monitoring.
         String event = MavenEvents.PROJECT_EXECUTION;
@@ -304,13 +305,11 @@ public class DefaultMaven
      * @todo [JC] we should at least provide a mapping of protocol-to-proxy for
      * the wagons, shouldn't we?
      */
-    private void resolveParameters( MavenExecutionRequest request )
+    private void resolveParameters( Settings settings )
         throws ComponentLookupException
     {
         WagonManager wagonManager = (WagonManager) container.lookup( WagonManager.ROLE );
 
-        Settings settings = request.getSettings();
-
         Proxy proxy = settings.getActiveProxy();
 
         if ( proxy != null )
@@ -326,6 +325,13 @@ public class DefaultMaven
             wagonManager.addAuthenticationInfo( server.getId(), server.getUsername(), server.getPassword(),
                                                 server.getPrivateKey(), server.getPassphrase() );
         }
+
+        for ( Iterator i = settings.getMirrors().iterator(); i.hasNext(); )
+        {
+            Mirror mirror = (Mirror) i.next();
+
+            wagonManager.addMirror( mirror.getId(), mirror.getMirrorOf(), mirror.getUrl() );
+        }
     }
 
     // ----------------------------------------------------------------------

maven-core/src/main/java/org/apache/maven/settings/MavenSettingsBuilder.java

@@ -1,9 +1,5 @@
 package org.apache.maven.settings;
 
-import org.codehaus.plexus.util.xml.pull.XmlPullParserException;
-
-import java.io.IOException;
-
 /*
  * Copyright 2001-2005 The Apache Software Foundation.
  *
@@ -20,6 +16,10 @@ import java.io.IOException;
  * limitations under the License.
  */
 
+import org.codehaus.plexus.util.xml.pull.XmlPullParserException;
+
+import java.io.IOException;
+
 /**
  * @author jdcasey
  * @version $Id$

maven-project/src/main/resources/org/apache/maven/project/pom-4.0.0.xml

@@ -13,7 +13,7 @@
 
   <pluginRepositories>
     <pluginRepository>
-      <id>plugin-central</id>
+      <id>central</id>
       <name>Maven Plugin Repository</name>
       <url>http://repo1.maven.org/maven2</url>
       <layout>default</layout>

maven-site/src/site/xdoc/configuration.xml

@@ -93,7 +93,7 @@
   .
   .]]></source>
       <p style="font-weight: bold; font-size: larger">
-        Deployment Settings
+        Security and Deployment Settings
       </p>
       <p>
         Repositories to deploy to are defined in a project in the <code>&lt;distributionManagement&gt;</code> section.
@@ -101,6 +101,10 @@
         you should add a server definition to your own settings with an <code>id</code> that matches that of the
         deployment repository in the project.
       </p>
+      <p>
+        In addition, some repositories may require authorisation to download from, so the corresponding settings can
+        be specified in a <code>server</code> element in the same way.
+      </p>
       <p>
         Which settings are required will depend on the type of repository you are deploying to. As of the first release,
         only SCP deployments and file deployments are supported by default, so only the following SCP configuration
@@ -123,6 +127,47 @@
   </servers>
   .
   .]]></source>
+      <p style="font-weight: bold; font-size: larger">
+        Using Mirrors for Repositories
+      </p>
+      <p>
+        Repositories are declared inside a project, which means that if you have your own custom repositories, those
+        sharing your project easily get the right settings out of the box. However, you may want to use an alternative
+        mirror for a particular repository without changing the project files.
+      </p>
+      <p>
+        Some reasons to use a mirror are:
+      </p>
+      <ul>
+        <li>There is a synchronized mirror on the internet that is geographically closer and faster</li>
+        <li>You want to replace a particular repository with your own internal repository which you have greater
+          control over</li>
+        <li>You want to run maven-proxy to provide a local cache to a mirror and need to use it's URL instead</li>
+      </ul>
+      <p>
+        To configure a mirror of a given repository, you provide it in your settings file, giving the new repository
+        it's own <code>id</code> and <code>url</code>, and specify the <code>mirrorOf</code> setting that is the ID of
+        the repository you are using a mirror of. For example, the ID of the main Maven repository included by default is
+        <code>central</code>, so to use an Australian mirror, you would configure the following:
+      </p>
+      <source><![CDATA[
+<settings>
+  .
+  .
+  <mirrors>
+   <mirror>
+      <id>planetmirror</id>
+      <name>Australian Mirror of http://repo1.maven.org/maven2/</name>
+      <url>http://public.planetmirror.com/maven2/</url>
+      <mirrorOf>central</mirrorOf>
+    </mirror>
+  </mirrors>
+  .
+  .]]></source>
+      <p>
+        <i>Please note:</i> this particular is not actually set up for Maven 2 yet, so this should be treated as an
+        example only.
+      </p>
     </section>
   </body>
 </document>