View Source

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.

To use the mvn url handler is not required to have maven installed on the machine that runs the osgi framework. Having maven installed will actually only have an impact on the download speed as if the referenced artifacts are already in the local repository, case when those artifacts will be used as opposite of going over the net and download them from a remote repository.

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

Note that the versions from local repository (beside snapshot versions) are not taken in consideration as Maven does not create metadata for them. This maybe solved in the future by actually scanning the local repository directory to determine the versions.

Maven proxies (starting with version 0.3.2)

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

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.

This may be cause of subtle problems. pax-url-aether may be started before Configuration Admin is available. If Maven resolution is performed very early in the lifetime of OSGi runtime and if proper configuration is available only in etc/org.ops4j.pax.url.mvn.cfg then there may be short period of time where pax-url-aether is improperly configured. The solution is to duplicate the configuration in etc/config.properties as well.

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.

Option key	Description	Since
org.ops4j.pax.url.mvn.defaultRepositories	optional; a comma separated list for default repositories urls; see below
org.ops4j.pax.url.mvn.repositories	optional; a comma separated list for remote repositories urls; see below
org.ops4j.pax.url.mvn.localRepository	optional; the path to local repository directory; see below
org.ops4j.pax.url.mvn.useFallbackRepositories	optional; whether http://repo1.maven.org/maven2 should be used as one of implicit remote repositories
org.ops4j.pax.url.mvn.settings	optional; the path to settings.xml; see below
org.ops4j.pax.url.mvn.globalChecksumPolicy	optional; policy for handling checksums
org.ops4j.pax.url.mvn.globalUpdatePolicy	optional; remote maven repository update policy; see github
org.ops4j.pax.url.mvn.defaultLocalRepoAsRemote	optional; true/false if local repository should be used as first, implicit remote repository. Should always be `false`.
~~org.ops4j.pax.url.mvn.certificateCheck~~	~~optional; true/false if the SSL certificate check should be done. Default false.~~
~~org.ops4j.pax.url.mvn.proxySupport~~	~~optional; true/false if the proxy support is enabled . Default true.~~
org.ops4j.pax.url.mvn.timeout	timeout set for socket connection and read operations; used when `socket.readTimeout` or `socket.connectionTimeout` are not defined
org.ops4j.pax.url.mvn.socket.readTimeout	dedicated option for setting read timeout when accessing remote repositories	2.5.0
org.ops4j.pax.url.mvn.socket.connectionTimeout	dedicated option for setting connection timeout when accessing remote repositories	2.5.0
org.ops4j.pax.url.mvn.socket.linger	SO_LINGER option for sockets (see details here, default value is `-1`)	2.5.0
org.ops4j.pax.url.mvn.socket.reuseAddress	SO_REUSEADDDR option for sockets (see details here, default value is `false`)	2.5.0
org.ops4j.pax.url.mvn.socket.tcpNoDelay	TCP_NODELAY option for sockets (see details here, default value is `true`)	2.5.0
org.ops4j.pax.url.mvn.socket.keepAlive	SO_KEEPALIVE option for sockets (see details here, default value is `false`)	2.5.0
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`)	2.5.0
org.ops4j.pax.url.mvn.connection.retryCount	configuration option for Apache httpclient's `DefaultHttpRequestRetryHandler` (default value is `3`)	2.5.0

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:

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

Local repository

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

looks for a configuration property org.ops4j.pax.url.mvn.localRepository;
looks in settings.xml for <localRepository> element);
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:

looks for a org.ops4j.pax.url.mvn.repositories configuration property,
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 "+"
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

Remember, that global policies (either for checksums or updates) are always preferred over the ones specified at repository URI level!

See org.eclipse.aether.DefaultRepositorySystemSession#setUpdatePolicy() for more details.

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