Guide for Resolver Transport

Historically, since Maven 2.x, the only transport used by Maven was Maven Wagon. Since the introduction of the Resolver in Maven 3.x, it did “wrap” it in the maven-resolver-transport-wagon module, and continued to use it. Still, Wagon is deeply integrated with the old Plexus DI container and many, if not all, of its configuration are bound to be set in Plexus XML, which is not type safe, nor validated, nor future-proof.

Starting with Maven 3.9.0 release, the default transport (the default transport used by Maven Resolver) changed from ancient Wagon to modern maven-resolver-transport-http aka native HTTP transport.

Take a peek at the Resolver architecture diagram and the transport box contains several implementations, and this number will probably increase.

The Resolver contains configuration for many aspects, including transport (see the keys prefixed with aether.connector.). They can be found on resolver configuration page.

This page applies only to Maven 3.9.0 and newer.

Switching Between Transports

The transport used by resolver can be controlled using the -Dmaven.resolver.transport user property, for which accepted values are native (the default), wagon (uses legacy Wagon) and auto (delegates to resolver to sort out defaults).

The accepted values of maven.resolver.transport user property:

• default (implied if not present), does auto by default
• native forces use of transport-http
• wagon forces use of transport-wagon
• auto delegates to the resolver the transport choice (using aether.priority.<class> and related properties, or just relying on component priorities).

Note: forces means that the resolver will use the given transport even if another higher prioritized component is present on classpath.

Given the priority of native is higher than wagon, and that starting with Maven 3.9.0 both are present on resolver classpath, native is chosen by default. This behaviour preserves existing (pre 3.9.0) behaviour of Maven Resolver, that allowed third party transports to be added (by copying them to lib/ext) that have higher priorities. Still, fallback is possible with explicit use of native or wagon values.

Custom HTTP Headers

In all HTTP transports, you can add your custom HTTP headers like this:

<settings>
  <servers>
    <server>
      <id>my-server</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Foo</name>
            <value>Bar</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

It is important to understand that the above approach does not allow you to turn off all the default HTTP headers; nor does it allow you to specify headers on a per-method basis. However, this configuration remains available in all transports that support headers, like HTTP transports are (and works for “native” but also Wagon transport).

Timeouts

All transport implementations that perform some network access allow configuring several timeouts, for example to allow the user to tell Maven how long to wait before giving up on a connection that has not responded.

<settings>
  <servers>
    <server>
      <id>my-server</id>
      <configuration>
        <connectTimeout>10000</connectTimeout> <!-- milliseconds -->
        <requestTimeout>1800000</requestTimeout> <!-- milliseconds -->
      </configuration>
    </server>
  </servers>
</settings>

Low-level Resolver configuration

All configuration items mentioned in Configuration Options which are not mapped by server/configuration (eg.httpHeaders, timeout) tag must be provided in special way.

Some resolver configuration properties has a flag Supports Repo ID Suffix.

If you use property like:

aether.connector.http.preemptiveAuth=true

it means that preemptiveAuth will be applied for all of your repositories.

You can also add suffix to property with your repository ID in order to configure only for selected repository.

aether.connector.http.preemptiveAuth.myRepositoryId=true

it means that preemptiveAuth will be applied only for repository or mirror which has id as myRepositoryId

<settings>
  <profiles>
    <profile>
      <id>resolver-config</id>
      <properties>
        <aether.dependencyCollector.impl>bf</aether.dependencyCollector.impl>
        <!-- set preemptiveAuth for all repositories -->
        <aether.connector.http.preemptiveAuth>true</aether.connector.http.preemptiveAuth>
      </properties>
    </profile>
  </profiles>

  <activeProfiles>
    <!-- profile with configuration properties must be activated here -->
    <activeProfile>resolver-config</activeProfile>
  </activeProfiles>
</settings>

export MAVEN_ARGS="-Daether.connector.http.preemptiveAuth=true"

-Daether.dependencyCollector.impl=bf

$ mvn ... -Daether.enhancedLocalRepository.split \
          -Daether.enhancedLocalRepository.localPrefix=maven-resolver/mresolver-253
          -Daether.enhancedLocalRepository.splitRemoteRepository

How To Upgrade from Wagon? (or “native transport does not work”)

If your build environment uses Wagon specific configuration (in settings.xml or alike), you should migrate your configuration first. You can still upgrade and use latest Maven, with use -Dmaven.resolver.transport=wagon user property to stick with Wagon, but migration to new transport is warmly recommended.

Per Transport configuration details

Depending on which transport you use (native, wagon or something else), you will want to refer to the corresponding page(s) for detailed configuration options:

• For Native HTTP transport detailed configuration user properties are collected on this page.
• For Wagon you want to use -Dmaven.resolver.transport=wagon user property and configuration from this page.
• For any third party transport, please refer to its own documentation.