Default

...

Repositories

org.ops4j.pax.url.mvn.defaultRepositories - this is a comma-separated list of local repositories searched for an artifact in the first phase of artifact resolution. This repository should not contain URIs other than file://-based. Each repository from this list is treated as local repository. pax-url-aether iterates over this list and checks one repository at a time. If neither location contains the artifact being resolved, pax-url-aether switches to second phase that involves remote repositories. Also these repositories do not require write access - Aether doesn't write any files there.

...

singleRepositoryFromListOfDefaultRepositories means that we're trying one of repositories from org.ops4j.pax.url.mvn.defaultRepositories at a time. Each such local repository is checked independently.

Local Repository

org.ops4j.pax.url.mvn.localRepository - this is a local repository that supports Aether in second phase of artifact resolution. Its role is a bit different than the role of org.ops4j.pax.url.mvn.defaultRepositories. When Aether actually resolves artifact in one of the remote repositories, it stores the downloaded artifact to location specified in org.ops4j.pax.url.mvn.localRepository (or implied location). That's why write access is required for this location.

Second phase of artifact resolution can be presented using the following code:

RepositorySystem system = locator.getService(RepositorySystem.class);
RepositorySystemSession session = MavenRepositorySystemUtils.newSession();
 
String basedir = localRepository;
((DefaultRepositorySystemSession)session).setLocalRepositoryManager(system.newLocalRepositoryManager(session, new LocalRepository(basedir)));
 
ArtifactRequest req = new ArtifactRequest();
req.addRepository(new RemoteRepository.Builder("ID1", "default", "http://uri1").build());
req.addRepository(new RemoteRepository.Builder("ID2", "default", "http://uri2").build());
req.setArtifact(new DefaultArtifact("commons-io", "commons-io", "jar", "2.5"));
 
ArtifactResult res = system.resolveArtifact(session, req);

Here, for each remote repository from the list of URIs in org.ops4j.pax.url.mvn.repositories property we call org.eclipse.aether.resolution.ArtifactRequest.addRepository().

Also, basedir = localRepository means that we use local repository from org.ops4j.pax.url.mvn.localRepository property - the same local repository is used for each remote repository being searched.

Remote Repositories

org.ops4j.pax.url.mvn.repositories - this is a list of remote repositories searched for an artifact in the second phase of artifact resolution. This repository may contain URIs with file:// scheme, but it's better to add such repositories to org.ops4j.pax.url.mvn.defaultRepositories. Each repository is accessed using some configured connector (pax-url-aether uses a connector that underneath invokes httpclient 4.x library - that's why configuring org.apache.http.headers/shaded.org.apache.http.headers logger may be a good idea).

If a list of remote repositories in org.ops4j.pax.url.mvn.repositories is prefixed with + sign, all repositories available in all active profiles defined in settings.xml file are appended to effective list of remote repositories searched.

For example if we have this:

org.ops4j.pax.url.mvn.repositories= \
    +http://repo1.maven.org/maven2@id=maven.central.repo

And this in settings.xml:

<!--
    If org.ops4j.pax.url.mvn.repositories property is _prepended_ with '+' sign, repositories from all active
    profiles will be _appended_ to the list of searched remote repositories
-->
<profiles>
    <profile>
        <id>default</id>
        <repositories>
            <repository>
                <id>private.repository</id>
                <url>http://localhost:8181/maven-repository</url>
            </repository>
        </repositories>
    </profile>
</profiles>
<activeProfiles>
    <activeProfile>default</activeProfile>
</activeProfiles>

We will see this in logs during sample resolution:

18:10:17,734 | DEBUG | ... | Using transporter WagonTransporter with priority -1.0 for http://repo1.maven.org/maven2/
18:10:17,736 | DEBUG | ... | Using connector BasicRepositoryConnector with priority 0.0 for http://repo1.maven.org/maven2/
18:10:17,800 | DEBUG | ... | http-outgoing-8 >> GET /maven2/commons-io/commons-io/2.7/commons-io-2.7.jar HTTP/1.1
18:10:17,802 | DEBUG | ... | http-outgoing-8 >> Host: repo1.maven.org
...
18:10:17,872 | DEBUG | ... | Using transporter WagonTransporter with priority -1.0 for http://localhost:8181/maven-repository/
18:10:17,873 | DEBUG | ... | Using connector BasicRepositoryConnector with priority 0.0 for http://localhost:8181/maven-repository/
18:10:17,875 | DEBUG | ... | http-outgoing-9 >> GET /maven-repository/commons-io/commons-io/2.7/commons-io-2.7.jar HTTP/1.1
18:10:17,876 | DEBUG | ... | http-outgoing-9 >> Host: localhost:8181
...

Anchor
settings settings

settings.xml

...

• HTTP Proxies
• custom HTTP headers added when accessing particular remote repositories

Fallback repository

org.ops4j.pax.url.mvn.useFallbackRepositories - If true, then Aether will always use http://repo1.maven.org/maven2 repository in addition to any remote repositories specified. I prefer explicit declaration of Maven Central repository (if needed), so it's better to have false here.

HTTP Proxies

With pax-url-aether version 2.3.0 and later, http-wagon and httpclient libraries are used. HTTP proxies are configured inside settings.xml file. Here's the example:

<!--
    This is the place to configure http proxies used by Aether.
    If there's no proxy for "https" protocol, proxy for "http" will be used when accessing remote repository
-->
<proxies>
    <proxy>
        <id>proxy</id>
        <host>127.0.0.1</host>
        <port>3128</port>
        <protocol>http</protocol>
        <username></username>
        <password></password>
        <nonProxyHosts>127.0.0.*|*.repository.corp</nonProxyHosts>
    </proxy>
</proxies>

Custom Headers

Each remote repository specified in org.ops4j.pax.url.mvn.repositories should have id=IDENTIFIER option specified (see more about options in Repository Options). Having this identifier we may configure additional HTTP headers that will be send when accessing particular repository.

For example having this in settings.xml:

<!--
    pax-url-aether may use the below configuration to add custom HTTP headers when accessing remote repositories
    with a given identifier
-->
<servers>
    <server>
        <id>maven.central.repo</id>
        <configuration>
            <httpHeaders>
                <httpHeader>
                    <name>User-Agent</name>
                    <value>Karaf</value>
                </httpHeader>
                <httpHeader>
                    <name>Secret-Header</name>
                    <value>secret_value</value>
                </httpHeader>
            </httpHeaders>
        </configuration>
    </server>
</servers>

We will see these logs when accessing repository with ID=maven.central.repo:

17:30:44,590 | DEBUG | ... | http-outgoing-0 >> GET /maven2/commons-io/commons-io/2.7/commons-io-2.7.jar HTTP/1.1
17:30:44,590 | DEBUG | ... | http-outgoing-0 >> Cache-control: no-cache
17:30:44,590 | DEBUG | ... | http-outgoing-0 >> Cache-store: no-store
17:30:44,590 | DEBUG | ... | http-outgoing-0 >> Pragma: no-cache
17:30:44,591 | DEBUG | ... | http-outgoing-0 >> Expires: 0
17:30:44,591 | DEBUG | ... | http-outgoing-0 >> Accept-Encoding: gzip
17:30:44,591 | DEBUG | ... | http-outgoing-0 >> User-Agent: Karaf
17:30:44,591 | DEBUG | ... | http-outgoing-0 >> Secret-Header: secret_value
17:30:44,591 | DEBUG | ... | http-outgoing-0 >> Host: repo1.maven.org

Global Checksum Policy

org.ops4j.pax.url.mvn.globalChecksumPolicy - When Aether fetches artifact from remote repository, it always tries to download SHA1/MD5 checksum for the artifact. It may fail to do so. If repository URI doesn't specify per-repository value, this global property's value is used. Actually if this global value is specified, per-repository values are ignored. This property may have 3 values determining Aether's behavior:

• fail - resolution fails
• warn - information is printed at WARN level
• ignore - nothing happens.

Global Update Policy

org.ops4j.pax.url.mvn.globalUpdatePolicy - When Aether fetches SNAPSHOT artifacts, it needs to fetch maven-metadata.xml first. Before hitting each of org.ops4j.pax.url.mvn.repositories, Aether checks the presence of resolver-status.properties file in org.ops4j.pax.url.mvn.localRepository location (this status file is specific to given groupId, artifactId and version, for example: <REPOSITORY>/commons-io/commons-io/2.5-SNAPSHOT/resolver-status.properties). We can control whether Aether actually should refresh metadata information:

• always - Aether always fetches maven-metadata.xml when resolving SNAPSHOTs
• never - opposite of the above
• daily - Aether fetches maven-metadata.xml if a day passed since timestamp written in maven-metadata-ID_OF_REPOSITORY.xml.lastUpdated property inside resolver-status.properties file.
• interval:<NUMBER_OF_MINUTES> - Aether fetches maven-metadata.xml if given number of minutes passed.

Local Repository as Remote

org.ops4j.pax.url.mvn.defaultLocalRepoAsRemote - Whether local repository specified in org.ops4j.pax.url.mvn.localRepository should be added as first remote repository inserted to the list configured with org.ops4j.pax.url.mvn.repositories property - it's a bad idea... org.ops4j.pax.url.mvn.defaultRepositories should be used for this optimization purpose.

Sockets Configuration

Since version 2.5.0 of pax-url-aether, there are options to configure low-level socket details. Sockets (blocking I/O) are used at lowest level by Apache httpclient library. Here's a top-down list of layers used to actually access remote repositories using Java sockets:

• pax-url-aether
• Eclipse Aether
• Maven http-wagon
• Apache httpclient
• java.net Sockets

Here's a list of options that may be used:

• org.ops4j.pax.url.mvn.socket.readTimeout - configures read timeout for blocking I/O
• org.ops4j.pax.url.mvn.socket.connectionTimeout - configures timeout for establishing TCP connection
• org.ops4j.pax.url.mvn.socket.linger - SO_LINGER option for sockets (see details here, default value is -1)
• org.ops4j.pax.url.mvn.socket.reuseAddress - SO_REUSEADDDR option for sockets (see details here, default value is false)
• org.ops4j.pax.url.mvn.socket.tcpNoDelay - TCP_NODELAY option for sockets (see details here, default value is true)
• org.ops4j.pax.url.mvn.socket.keepAlive - SO_KEEPALIVE option for sockets (see details here, default value is false)
• org.ops4j.pax.url.mvn.connection.bufferSize - buffer size (read and write buffers) used by Apache httpclient when accessing remote repositories (default value is 8192)
• org.ops4j.pax.url.mvn.connection.retryCount - configuration option for Apache httpclient's DefaultHttpRequestRetryHandler (default value is 3)