Obr Protocol

Pax URL OBR is an OSGi URL handler that uses OBR (bundle repository) bundles based on bundle symbolic name and (optional) bundle version.The url handler is available starting with version 0.2.0 of Pax URL and is included into Pax Runner starting with version 0.7.0.

The OBR protocol handler uses available RFC-0112 Bundle Repository Repository Admin service implementation to discover the bundle. You can read more about on Apache Felix.

Note that in order to discover the resource Felix Bundle Repository has to parse the repository xml and this can be a time consuming process.

Why

Imagine this.

^© ( see original document )

OSGi specifications are being adopted at an increasing rate. The number of bundles available world wide is likely in the thousands, if not low ten thousands. Although many of these bundles are proprietary and not suitable for distribution, there are a large number of distributable bundles available. The current situation is that vendors have proprietary bundle repositories. However, in the open source community, the Oscar Bundle Repository allows end users to discover bundles using a command line tool that runs on any OSGi Framework.

Besides enabling bundle discovery, a repository can be used to simplify bundle provisioning by making it possible to create mechanisms to automate processing of deployment-related bundle requirements. The OSGi Framework already handles bundle requirement processing, such as resolving imported packages, required bundles, host bundles, and execution environments. However, the framework can only reason about and manage these requirements after bundles have been installed locally. Since bundles explicitly declare requirements in their manifest file, it is possible to define a bundle repository service that provides access to this metadata to enable remote reasoning about bundle provisioning. In general, bundle requirements are satisfied by capabilities provided by other bundles, the environment, or other resources. Resolving bundle requirements to provided capabilities is a constraint solving process. Some constraints are of a simple provide/require nature, while other constraints can include notions of versions and version ranges. One of the more complex constraints is the uses directive, which is used by package exporters to constrain package importers.
When a bundle is installed, all its requirements must be fulfilled. If its requirements can not be resolved, the bundle will fail to install or resolve. The missing requirements can potentially be resolved by installing other bundles; however, these bundles not only provide new capabilities, but they can also add new requirements that need to be resolved. This is a recursive process.

The OSGi specification defines numerous types of bundle requirements, such as Import Package, Require Bundle, Fragment Host, and Execution Environment. However, it is expected that new types of requirements and capabilities for resolving them will be defined in the future. Additionally, not all capabilities will be provided by bundles; for example, screen size or available memory could be capabilities.
Conceptually, capabilities can simply be viewed as the properties or characteristics of a bundle or the environment and requirements can be viewed as a selection constraint over these capabilities. On the whole, requirements are more complex than capabilities. The selection constraint of a requirement has two orthogonal aspects: multiple and optional. For example, an imported package is not optional and not multiple, while an
imported service could have multiple cardinality. Likewise, imported packages or services can be mandatory or optional.

Further, extends relationships allow a provider to extend another bundle. For example, a bundle fragment defines an extends relationship between a bundle and a host. Specifically, a given bundle requirement is a relationship that the bundle knows about in advance, as opposed to an extension, which may not have been known in advance by the bundle.
The process of resolving bundle requirements is complicated because it is non-trivial to find optimal solutions. The OSGi framework defines a run-time resolution process, which is concerned with many of the aspects described above. However, a provisioning resolution process for bundle discovery and deployment is also necessary, which is similar to the framework resolution process, but more generic.

Downloaded bundles are usually licensed. Licensing issues are complex and dependent on the vendor of the bundle. The way a bundle is licensed may seriously affect the way the bundle can be downloaded. Many organizations require their employees to read the license before they download the actual artifact because many licenses contain an implicit agreement.

Syntax ( see #examples )

obr-uri := 'obr:' bundle-symbolic-name [ '/' bundle-version ]
bundle-symbolic-name := < bundle symbolic name > ; symbolic name of the bundle
bundle-version := < bundle version > ; version of the bundle

Notes

• if version is not specified and more versions will be discovered in the bundle repository, the bundle with highest version number will be 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.

Repository configuration

The OBR protocol uses the OBR Repository Admin service available to discover the bundle. In case of Felix Bundle Repository you have to set the obr.repository.url to a space separated list of repositories urls. For use the OSGi Alliance repository you have to set:

obr.repository.url=http://bundles.osgi.org/obr/browse?_xml=1&cmd=repository

Note that the above repository (http://bundles.osgi.org/obr/browse?_xml=1&cmd=repository) is the default value when the OBR is used within Pax Runner and the value can be used using the obrRepositories or obrRepos startup options.

Examples

Refers to Eclipse Equinox Http Service implementation:

obr:org.eclipse.equinox.http

Refers to Eclipse Equinox Http Service implementation version 1.0.100.v20070423 :

obr:org.eclipse.equinox.http/1.0.100.v20070423