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 )

mvn-uri := 'mvn:' [ repository-url '!' ] group-id '/' artifact-id [ '/' [version] [ '/' [type] [ '/' classifier ] ] ] ]
repository-url := < rfc2396 uri > ; an url that points to a maven 2 repository
group-id := < maven groupId > ; group id of maven artifact
artifact-id := < maven artifactId > ; artifact id of maven artifact
version := < maven version > | 'LATEST' | range ; version of maven artifact
range := ( '[' | '(' ) version ',' version ( ')' | ']' )
type := < maven type> ; type of maven artifact
classifier := < maven classifier> ; maven artifact classifier

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.

Settings.xml

Detailed information about settings.xml usage is described in settings.xml.

If necessary the handler will make use if possible of maven settings.xml using the following resolution:

1. looks for a configuration property org.ops4j.pax.url.mvn.settings
2. if not found looks for ${user.home}/.m2/settings.xml
3. if not found looks for ${maven.home}/conf/settings.xml
4. if not found looks for ${M2_HOME}/conf/settings.xml

Local repository

The local repository will be resolved by using the following resolution:

1. looks for a configuration property org.ops4j.pax.url.mvn.localRepository;
2. looks in settings.xml for <localRepository> element);
3. falls back to ${user.home}/.m2/repository.

As described earlier, local repository is used to store artifacts downloaded from remote repositories. Further resolutions of the same artifact won't require external repository access if the artifact is available in local repository.

Repositories

org.ops4j.pax.url.repositories is a comma separated list of remote repositories to be used when artifact needs to be resolved/retrieved, but it's not available in both default repositories and local repository. An @id is required for all URLs otherwise it will be ignored (e.g., http://repository.ops4j.org/mvn-snapshots@snapshots@id=ops4j-snapshot). If repository access requests authentication the user name and password must be specified in the repository URL as for example http://user:password@repository.ops4j.org/maven2.

If the repositories from configuration starts with a plus sign ("+"), the option 2 is also used and the repositories from settings.xml will be appended to the list.
Repositories resolution:

1. looks for a org.ops4j.pax.url.mvn.repositories configuration property,
2. looks in settings.xml for <repository> elements. Only repositories from active profiles are considered. Before pax-url-aether 2.5.0, active profiles were those explicitly specified in <activeProfiles>/<activeProfile>. Version 2.5.0 also takes into account those profiles that have <activation>/<activeByDefault> set to true. These repositories are appended to the list of original repositories from org.ops4j.pax.url.mvn.repositories, if the value of this option starts with "+"
3. if org.ops4j.pax.url.mvn.defaultLocalRepoAsRemote is set to true (not recommended!), local repository is used as first remote repository.

Here's the example:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <profiles>
    <profile>
      <id>development</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <repositories>
        <repository>
          <id>ops4j-snapshot</id>
          <name>ops4j.org snapshot repository</name>
          <url>http://repository.ops4j.org/mvn-snapshots/</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
        <repository>
          <id>ops4j</id>
          <name>ops4j.org release repository</name>
          <url>http://repository.ops4j.org/maven2/</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </repository>
        <repository>
          <id>ops4j-runner-snapshot</id>
          <name>ops4j.org pax runner snapshot repository</name>
          <url>http://scm.ops4j.org/repos/ops4j/projects/pax/runner-repository</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <!-- for a version that fixes PAXEXAM-159 and 160 -->
        <pluginRepository>
          <id>ops4j-plugin-snapshot</id>
          <name>ops4j.org snapshot repository</name>
          <url>http://repository.ops4j.org/mvn-snapshots/</url>
        </pluginRepository>
        <pluginRepository>
          <id>apache-plugin-snapshot</id>
          <name>apache.org snapshot repository</name>
          <url>http://repository.apache.org/content/groups/snapshots-group</url>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>development</activeProfile>
  </activeProfiles>
</settings>

Marking repositories as containing releases / snapshots (starting with release 0.2.1)

Usually repositories (not local repository) contains either releases or snapshot artifacts. In order to speed up the artifact locations discovery you can mark the repository with the type of artifacts it contains. This is similar with setting the release/enabled / snapshots/enabled tags in pom.xml or settings.xml.

By default (no marking) the local repository is considered as containing both releases and snapshots and the other repositories as containing only releases (same behavior as Maven).

You can alter this default behavior by adding the following to repository url (not case sensitive):

• to enable snapshots - add @snapshots
• to disable releases - add @noreleases

You can add this markings in any order and you can add them both to an url. Here are some examples:

http://repository.ops4j.org ; default no markings: searched only for releases, no snapshots
http://repository.ops4j.org/mvn-snapshots@snapshots ; searched for releases and snapshots
http://repository.ops4j.org/mvn-snapshots@snapshots@noreleases ; searched snapshots, no releases

Default repositories (starting with release 0.3.3)

In some cases, it may be useful to have more control of the list of repositories used to avoid the user settings to affect the download of artifacts. This can be done by configuring the defaultRepositories property to a list of repositories URLs. If this property is defined, the configured repositories will be checked first, before checking the local repository and other remote repositories configured using the repositories property. This property is available for pax-url >= 0.3.3.

Repository options

When specifying URI on a org.ops4j.pax.url.mvn.repositories list, we may use the following format:

http(s)://host:port/path@snapshots@noreleases@id=ID@other_options

Options that may be specified are:

• id=ID - this option should be specified to identify a repository. We may then refer to the repository for example when specifying Aether Configuration.
• snapshots - whether the repository should be used when resolving SNAPSHOT artifacts
• noreleases - whether the repository should not be used when resolving non-SNAPSHOT artifacts
• releasesUpdate=daily|never|always|interval:MINUTES - see description of org.ops4j.pax.url.mvn.globalUpdatePolicy property
• snapshotsUpdate=daily|never|always|interval:MINUTES - see description of org.ops4j.pax.url.mvn.globalUpdatePolicy property
• update=daily|never|always|interval:MINUTES - see description of org.ops4j.pax.url.mvn.globalUpdatePolicy property
• releasesChecksum=fail|warn|ignore - see description of org.ops4j.pax.url.mvn.globalChecksumPolicy property
• snapshotsChecksum=fail|warn|ignore - see description of org.ops4j.pax.url.mvn.globalChecksumPolicy property
• checksum=fail|warn|ignore - see description of org.ops4j.pax.url.mvn.globalChecksumPolicy property

Examples

Refers to version 0.2.0 of Pax Web that will be resolved from local repository and optionaly other repositories configured in #settings.xml

mvn:org.ops4j.pax.web.bundles/service/0.2.0 - an artifact that will be resolved based on the configured repositories

Refers to latest version of Pax Web that will be resolved from local repository and optionaly other repositories configured in #settings.xml

mvn:org.ops4j.pax.web.bundles/service
mvn:org.ops4j.pax.web.bundles/service/LATEST

Refers to snapshot version of Pax Web that will be resolved from local repository and optionaly other repositories configured in #settings.xml

mvn:org.ops4j.pax.web.bundles/service/0.2.0-SNAPSHOT

Refers to version 0.2.0 of Pax Web from OPS4J repository. Only the specified repository will not be used during resolution.

mvn:http://repository.ops4j.org/maven2!org.ops4j.pax.web.bundles/service/0.2.0

- an artifact from an http repository

Refers to version 0.2.0 of Pax Web from OPS4J repository; the user / password will be used for authentication if required. Only the specified repository will not be used during resolution.

mvn:http://user:password@repository.ops4j.org/maven2!org.ops4j.pax.web.bundles/service/0.2.0

Refers to version 0.2.0 of Pax Web from a repository starting at c:/localRepo. Only the specified repository will not be used during resolution.

mvn:file://c:/localRepo!org.ops4j.pax.web.bundles/service/0.2.0 - an artifact from a directory

Refers to version 0.2.0 of Pax Web from a repository packed in a zip file. Only the specified repository will not be used during resolution.

 mvn:jar:file://c:/repo