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 bypom.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
ormvn:groups/artifact/version//classifier
ormvn: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.
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.
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 | |
|
| |
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 totrue
. These repositories are appended to the list of original repositories fromorg.ops4j.pax.url.mvn.repositories
, if the value of this option starts with "+
" - if
org.ops4j.pax.url.mvn.defaultLocalRepoAsRemote
is set totrue
(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 artifactsnoreleases
- whether the repository should not be used when resolving non-SNAPSHOT artifactsreleasesUpdate=daily|never|always|interval:MINUTES
- see description oforg.ops4j.pax.url.mvn.globalUpdatePolicy
propertysnapshotsUpdate=daily|never|always|interval:MINUTES
- see description oforg.ops4j.pax.url.mvn.globalUpdatePolicy
propertyupdate=daily|never|always|interval:MINUTES
- see description oforg.ops4j.pax.url.mvn.globalUpdatePolicy
propertyreleasesChecksum=fail|warn|ignore
- see description oforg.ops4j.pax.url.mvn.globalChecksumPolicy
propertysnapshotsChecksum=fail|warn|ignore
- see description oforg.ops4j.pax.url.mvn.globalChecksumPolicy
propertychecksum=fail|warn|ignore
- see description oforg.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