Mvn Protocol

Maven protocol (via URIs starting with mvn:) enables you access to maven repository artifacts based on well known by now groupId, artifactId, version, type and classifier.

For low level details, please see information in Maven Guide.

There are three kinds of repositories involved (in the order of access):

• default repositories (0…N) - these are local repositories checked initially in the process of artifact resolution. If any of default repositories contain required artifact, no remote repository is accessed and no HTTP traffic is generated

• local repository (1) - when artifact can't be found in any of default repositories, pax-url-aether starts checking remote repositories. Each remote repository access is associated with local repository. If artifact is found in remote repository and retrieved it is written to local repository. Following resolution attempt of the same artifact still won't end with artifact being found in default repositories, but this time no remote repository will be accessed, because artifact is already available in local repository.

• remote repositories (0…N) - these are external repositories accessed when no local version of artifact can't be found.

Aether library (used internally by pax-url-aether) has only the concept of local and remote repository. Default repository is pax-url-aether library concepts that makes configuration clearer.

There's important consequence of the above separation:

• default repositories may be treated as collection of read-only repositories. They should be file:// based and often are defined as NFS shared locations (in multicontainer environments)

• local repository should be treated as single, mandatory, read-write repository. It plays very similar role as usual ~/.m2/repository during ordinary Maven builds - when Maven build finishes, your ~/.m2/repository should contain all the artifacts required by pom.xml - Aether will store them there.

• but using ~/.m2/repository as local repository is not necessarily a good idea in production environment. For example - if there is more than one Karaf container running on single computer, and all containers have the same local repository configured, there may be situations where Aether file deadlocks occur - if more than one Karaf instance tries to download the same remote artifact from remote repository. The reason is that each remote access should (eventually) end with the remotely available artifact to be stored locally.

• because of the above, it's better to use ~/.m2/repository as one of the default repositories (together with e.g., ${karaf.home}/system) and configure local repository as private location for the container.

In the process of resolving the artifact, the handler will make use of local repository if possible or any set of remote repositories including existing metadata for resolving latest of a snapshot version.

Syntax ( see #examples )

Notes

• If version is not specified default value LATEST will be used meaning and will try to resolve the latest version from available maven metadata;

• If version is a SNAPSHOT version, SNAPSHOT will be resolved from available maven metadata using the same resolution as maven;

• If type is not specified default value JAR will be used.

• To specify a type but not specify a version you will have leave the version "spot" empty as in mvn:groups/artifact//type

• Classifier is supported only starting with version 0.3.0 of Pax URL

• If classifier is not specified, no classifier will be used

• To specify a classifier but not specify a version or type you will have leave the version and/or type "spots" empty as in mvn:groups/artifact///classifier or mvn:groups/artifact/version//classifier or mvn:groups/artifact//type/classifier

Version range (starting with version 0.2.0)

If the version is specified as a range, the version will be resolved by first resolving all versions for that artifact from all available repositories. Then the version with the higher version number that can be downloaded will be used. The square brackets denotes an inclusive range and the rounded brackets denote an exclusive range.
For example mvn:commons-logging/commons-logging/[1.0,1.1) will be resolved as version 1.0.4 as being the highest version that fits the range.
Here are some examples, where x is a version that is found in maven metadata:

• [1.2.3, 4.5.6) — 1.2.3 <= x < 4.5.6

• [1.2.3, 4.5.6] — 1.2.3 <= x <= 4.5.6

• (1.2.3, 4.5.6) — 1.2.3 < x < 4.5.6

• (1.2.3, 4.5.6] — 1.2.3 < x <= 4.5.6

Maven proxies (starting with version 0.3.2)

Detailed configuration of HTTP proxies used during Maven resolution is described in HTTP Proxies.

Read more about Maven proxies here.

With pax-url-aether 2.3.0, HTTP proxy configuration was totally rewritten. Before 2.3.0, pax-url-aether used wagon-http-lightweight library that had issues with proxies (affecting JVM-wide configuration using system properties). With version 2.3.0, wagon-http and Apache HTTP Client libraries are used.

Configuration

The service can be configured in two ways: via configuration admin if available and via framework/system properties where the configuration via config admin has priority.

In other words, when pax-url-aether starts it checks whether Configuration Admin is available. If no, then properties available from BundleContext (configured e.g., inside etc/config.properties of Karaf) are used. When Configuration Admin becomes available, configuration with org.ops4j.pax.url.mvn PID is used.

Configuration options are described in more details in Aether Configuration. Here's a brief summary of options (properties in org.ops4j.pax.url.mvn PID or in etc/config.properties file when/while Configuration Admin service is not (yet) available.