|
Maven protocol enables you access to maven repository artifacts based on well known by now groupId, artifactId, version and type.
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 mnv 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 articats are already in the local repository, case when those artifacts will be used as oposite of going over the net and download them from a remote repository.
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 clasifier
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 (besie 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)
mvn protocol handler is able to use the maven proxy concept. This proxies allows setting of proxies in case that there is no direct connection to internet. Read more about maven proxies here. By default the support for proxies is enabled but can be disabled by using configuration option org.ops4j.pax.url.mvn.proxySupport (see configuration bellow).
Currently only http proxies are supported, as http proxies are the most common use case.
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.
| Option key |
Description |
| org.ops4j.pax.url.mvn.certificateCheck |
optional; true/false if the SSL certificate check should be done. Default false. |
| org.ops4j.pax.url.mvn.localRepository |
optional; the path to local repository directory; see bellow |
| org.ops4j.pax.url.mvn.repositories |
optional; a comma separated list for repositories urls; see bellow |
| org.ops4j.pax.url.mvn.settings |
optional; the path to settings.xml; see bellow |
| org.ops4j.pax.url.mvn.proxySupport |
optional; true/false if the proxy support is enabled . Default true. |
Settings.xml
If necessary the handler will make use if possible of maven settings.xml using the following resolution:
- looks for a configuration property
- 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;
- looks in settings.xml (see settings.xml resolution);
- falls back to ${user.home}/.m2/repository.
Repositories
Repositories is a comma separated list of repositories to be used. If repository acces 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  the option 2 is also used and the repositories from settings.xml will be appended to the list.
Repositories resolution:
- looks for a configuration property
- looks in settings.xml (see settings.xml resolution). In this case all configured repositories with a non classic layout will be used including configured user/password.
Note that the local repository is added as the first repository if exists.
Marking repositories as containing releases / snapshots (starting with release 0.2.1)
Usually repositories (not local repo) contains either releases or snapshots 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:
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.
- 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.
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.
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.
Issue tracker
Issues, bugs, and feature requests can be submitted to the issue tracking system.
| 
