maven repository setting.xml the mirrorof

Question

<mirrors>
    <!-- mirror
     | Specifies a repository mirror site to use instead of a given repository. The repository that
     | this mirror serves has an ID that matches the mirrorOf element of this mirror. IDs are used
     | for inheritance and direct lookup purposes, and must be unique across the set of mirrors.
     |
    <mirror>
      <id>mirrorId</id>
      <mirrorOf>repositoryId</mirrorOf>
      <name>Human Readable Name for this Mirror.</name>
      <url>http://my.repository.com/repo/path</url>
    </mirror>
     -->
    <mirror>
        <id>nexus-osc</id>
        <mirrorOf>central</mirrorOf>
        <name>Nexus osc</name>
        <url>http://maven.oschina.net/content/groups/public/</url>
    </mirror>
    <mirror>
        <id>nexus-osc-thirdparty</id>
        <mirrorOf>thirdparty</mirrorOf>
        <name>Nexus osc thirdparty</name>
        <url>http://maven.oschina.net/content/repositories/thirdparty/</url>
    </mirror>
    <mirror>
        <id>maven2</id>
        <mirrorOf>maven2</mirrorOf>
        <name>maven2</name>
        <url>http://repo1.maven.org/maven2/</url>
    </mirror>
</mirrors>

What is the exactly using of mirrorOf? Will maven first try get jar from id=nexus-osc and then nexus-osc-thirdparty and then maven2? I have already checked the maven mirror setting guide but I still can not understand.

Solution

Quoting the Maven documentation about mirrors:

To configure a mirror of a given repository, you provide it in your settings file (${user.home}/.m2/settings.xml), giving the new repository its own id and url, and specify the mirrorOf setting that is the ID of the repository you are using a mirror of.

What this means is that mirrorOf points to an existing repository declaration and configures Maven to use that mirror when it attempts to connect the the specified repository.

---

Let's take an example. You have a project with the following repository defined in your project:

<project>
  ...
  <repositories>
    <repository>
      <id>my-internal-site</id>
      <url>http://myserver/repo</url>
    </repository>
  </repositories>
  ...
</project>

with the following declaration in your settings:

<settings>
  ...
  <mirrors>
    <mirror>
      <id>UK</id>
      <name>UK Central</name>
      <url>http://uk.maven.org/maven2</url>
      <mirrorOf>my-internal-site</mirrorOf>
    </mirror>
  </mirrors>
  ...
</settings>

What this means is that whenever Maven will attempt to download a library from the my-internal-site repository, it will actually not use http://myserver/repo but, instead, use the mirror declaration and download the library from http://uk.maven.org/maven2.

It does not define any order. It just declares where Maven needs to download artifacts in place of the mirrored repository.

---

Specifying <mirrorOf>central</mirrorOf> tells Maven that you are mirroring the Maven Central repository which is the default location where Maven downloads artifacts from.

---

As such, using mirrors is often used in enterprise context when you have a central internal repository and every Maven request goes through that repository manager.

Comments

[Corey]

By doing so, would it clone libraries from central and then copy the libraries to the internal repository?