OBR

The goal of OBR (OSGi Bundle Repository) is:

to simplify deploying and using bundles
to encourage independent bundle development.

OBR achieves the first goal by providing a service that can automatically install a bundle, with its deployment dependencies, from a bundle repository. This makes it easier for people to experiment with existing bundles.

The second goal is achieved by raising the visibility of the available bundles in a repository.

OBR is an optional Apache Karaf feature. You have to install the obr feature to use OBR service:

karaf@root()> feature:install obr

The OBR feature turns Apache Karaf as an OBR client. It means that Apache Karaf can use a OBR repository to the installation of the bundles, and during the installation of the features.

The installation of the obr feature adds in Apache Karaf:

the OBR service
the features OBR resolver
the obr:* commands
the JMX ObrMBean

The OBR repository contains all bundles. The OBR service knows all requirements and capabilities of each bundle on an OBR repository (it’s the OBR metadata).

Thanks to that, when you install ("deploy" in OBR wording) a bundle using the OBR service, it looks for all bundles providing the capabilities matching the bundle requirements. It will automatically install the bundles needed for the bundle.

Features OBR resolver

If the feature specifies obr in the resolver attribute, Apache Karaf can use the OBR service to construct the list of bundles to install with the features.

The feature default resolver just consider the bundles described in the feature itself.

Using the OBR resolver, Apache Karaf can extend the bundle list at the feature installation time using the OBR service.

Commands

`obr:url-add`

The obr:url-add command registers the OBR repository at a given URL in the OBR service.

Basically, an OBR repository is described by a repository.xml file.

The obr:url-add command expects an url argument. The url argument is the URL to the OBR repository repository.xml file. Any URL described in the [Artifacts repositories and URLs section|urls] is supported.

For instance:

karaf@root()> obr:url-add file:///user/.m2/repository/repository.xml

`obr:url-list`

The obr:url-list command lists the OBR repository (with URL) registered in the OBR service:

karaf@root()> obr:url-list
Index | OBR URL
---------------------------------------------------------
0     | file:/user/.m2/repository/repository.xml

`obr:url-refresh`

The obr:url-refresh command refresh an OBR repository (reloading the URL).

The OBR service doesn’t take "on the fly" the changes performed on an OBR repository repository.xml. You have to reload the repository.xml URL to take the changes. It’s the purpose of the obr:url-refresh command.

Without argument, the obr:url-refresh command refreshes all repositories:

karaf@root()> obr:url-refresh

You can refresh only one repository by specifying the URL as argument:

karaf@root()> obr:url-refresh file:/user/.m2/repository/repository.xml

Instead of using the URL, you can use the repository index as displayed by the obr:url-list command. To do so, you have to use the -i option:

karaf@root()> obr:url-refresh -i 0

`obr:url-remove`

The obr:url-remove command removes an OBR repository from the OBR service.

The obr:url-remove command expects the repository URL as argument:

karaf@root()> obr:url-remove file:/user/.m2/repository/repository.xml

Instead of using the URL, you can use the repository index as displayed by the obr:url-list command. To do so, you have to use the -i option:

karaf@root()> obr:url-remove -i 0

`obr:list`

The obr:list command lists all bundles available on the registered OBR repositories:

karaf@root()> obr:list|more
Name                                                                         | Symbolic Name                                                             | Version
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
activemq-blueprint                                                           | org.apache.activemq.activemq-blueprint                                    | 5.10.0.SNAPSHOT
activemq-camel                                                               | org.apache.activemq.activemq-camel                                        | 5.10.0.SNAPSHOT
activemq-karaf                                                               | activemq-karaf                                                            | 5.10.0.SNAPSHOT
activemq-osgi                                                                | org.apache.activemq.activemq-osgi                                         | 5.10.0.SNAPSHOT
Apache Aries Application API                                                 | org.apache.aries.application.api                                          | 1.0.1.SNAPSHOT
...

`obr:info`

The obr:info command displays the details about bundles available on the OBR service. Especially, it provides details about capabilities and requirements of bundles.

The obr:info command expects a bundle symbolic name as argument:

karaf@root()> obr:info org.apache.karaf.wrapper.core
-------------------------------
Apache Karaf :: Wrapper :: Core
-------------------------------
id: org.apache.karaf.wrapper.core/3.0.0
description: Core implementation and integration of the Java Service Wrapper.        It provides a complete integration of Karaf with your Operating System.
documentation: http://www.apache.org/
symbolicname: org.apache.karaf.wrapper.core
presentationname: Apache Karaf :: Wrapper :: Core
license: http://www.apache.org/licenses/LICENSE-2.0.txt
uri: file:/user/.m2/repository/org/apache/karaf/wrapper/org.apache.karaf.wrapper.core/3.0.0/org.apache.karaf.wrapper.core-3.0.0.jar
size: 1281352
version: 3.0.0
Requires:
   service:(&(service=org.apache.aries.blueprint.NamespaceHandler)(osgi.service.blueprint.namespace=http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0))
   package:(&(package=javax.management))
   package:(&(package=org.apache.karaf.wrapper))
   package:(&(package=org.apache.karaf.wrapper.management))
   package:(&(package=org.fusesource.jansi)(version>=1.11.0)(!(version>=2.0.0)))
   package:(&(package=org.osgi.framework)(version>=1.7.0)(!(version>=2.0.0)))
   package:(&(package=org.osgi.framework.launch)(version>=1.1.0)(!(version>=2.0.0)))
   package:(&(package=org.osgi.framework.startlevel)(version>=1.0.0)(!(version>=2.0.0)))
   package:(&(package=org.osgi.service.blueprint)(version>=1.0.0)(!(version>=2.0.0)))
   package:(&(package=org.slf4j)(version>=1.7.0)(!(version>=2.0.0)))
Capabilities:
   bundle:{manifestversion=2, symbolicname=org.apache.karaf.wrapper.core, presentationname=Apache Karaf :: Wrapper :: Core, version=3.0.0}
   service:{service=org.apache.karaf.wrapper.WrapperService}
   package:{package=org.apache.karaf.wrapper, version=3.0.0}
   package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=3.0.0}

The obr:info command uses the following syntax to identify the bundles: symbolic_name,version where version is optional. It means that you have to use the following command to see the info about the wrapper core bundle with version 3.0.0:

karaf@root()> obr:info org.apache.karaf.wrapper.core,3.0.0
...

You can specific multiple bundles separated by space:

karaf@root()> obr:info org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0
...

`obr:source`

In addition of the bundles executable, the OBR service can also store the bundles sources.

The obr:source command check the source URL in the OBR metadata for a given bundle, and download the sources on a target folder:

karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core

The obr:source command uses the following syntax to identify the bundles: symbolic_name,version where version is optional. It means that you have to use the following command to download the source of wrapper core bundle with version 3.0.0:

karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,3.0.0

You can specify multiple bundles separated by space:

karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0
...

`obr:resolve`

The obr:resolve command displays the resolution output for a given set of requirements. Actually, it show the bundles providing the capabilities to match the requirements. It’s what the OBR service does when executing obr:deploy.

Optionally, the obr:resolve command can deploy the bundles as the obr:deploy command does.

For instance, to know the OBR bundle resolving the org.apache.karaf.wrapper package requirement, you can do:

karaf@root()> obr:resolve package=org.apache.karaf.wrapper
Required resource(s):
---------------------
   Apache Karaf :: Wrapper :: Core (3.0.0)

`obr:find`

The obr:find command is similar to the obr:resolve one. It displays the bundles resolving the provided requirements, with details.

For instance, to find the OBR bundle providing the org.apache.karaf.wrapper package, you can do:

karaf@root()> obr:find package=org.apache.karaf.wrapper
-------------------------------
Apache Karaf :: Wrapper :: Core
-------------------------------
id: org.apache.karaf.wrapper.core/3.0.0
description: Core implementation and integration of the Java Service Wrapper.        It provides a complete integration of Karaf with your Operating System.
documentation: http://www.apache.org/
symbolicname: org.apache.karaf.wrapper.core
presentationname: Apache Karaf :: Wrapper :: Core
license: http://www.apache.org/licenses/LICENSE-2.0.txt
uri: file:/user/.m2/repository/org/apache/karaf/wrapper/org.apache.karaf.wrapper.core/3.0.0/org.apache.karaf.wrapper.core-3.0.0.jar
size: 1281352
version: 3.0.0
Requirements:
   service:(&(service=org.apache.aries.blueprint.NamespaceHandler)(osgi.service.blueprint.namespace=http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0))
   package:(&(package=javax.management))
   package:(&(package=org.apache.karaf.wrapper))
   package:(&(package=org.apache.karaf.wrapper.management))
   package:(&(package=org.fusesource.jansi)(version>=1.11.0)(!(version>=2.0.0)))
   package:(&(package=org.osgi.framework)(version>=1.7.0)(!(version>=2.0.0)))
   package:(&(package=org.osgi.framework.launch)(version>=1.1.0)(!(version>=2.0.0)))
   package:(&(package=org.osgi.framework.startlevel)(version>=1.0.0)(!(version>=2.0.0)))
   package:(&(package=org.osgi.service.blueprint)(version>=1.0.0)(!(version>=2.0.0)))
   package:(&(package=org.slf4j)(version>=1.7.0)(!(version>=2.0.0)))
Capabilities:
   bundle:{manifestversion=2, symbolicname=org.apache.karaf.wrapper.core, presentationname=Apache Karaf :: Wrapper :: Core, version=3.0.0}
   service:{service=org.apache.karaf.wrapper.WrapperService}
   package:{package=org.apache.karaf.wrapper, version=3.0.0}
   package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=3.0.0}

`obr:deploy`

The obr:deploy command installs a bundle from the OBR repository, including all bundles required to satisfy the bundle requirements.

karaf@root()> obr:deploy org.ops4j.pax.web.samples.helloworld-hs
Target resource(s):
-------------------
   OPS4J Pax Web - Samples - Hello World - HttpService (4.0.0.SNAPSHOT)

Required resource(s):
---------------------
   Apache ServiceMix :: Specs :: Activation API 1.4 (2.3.0.SNAPSHOT)
   OPS4J Pax Web - Jetty Bundle (4.0.0.SNAPSHOT)

Deploying...done.

By default, the bundles are just installed, not started. You can use the -s option to start the bundles.

The obr:deploy command uses the following syntax to identify the bundles: symbolic_name,version where version is optional. It means that you have to use the following command to deploy the wrapper core bundle with version 3.0.0:

karaf@root()> obr:deploy org.apache.karaf.wrapper.core,3.0.0

You can specify multiple bundles separated by space:

karaf@root()> obr:deploy org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0
...

`obr:start`

The obr:start command does the same as obr:deploy -s command. It installs the bundle (and all required bundles to satisfy the requirements) and starts all installed bundles.

karaf@root()> obr:start org.ops4j.pax.web.samples.helloworld-hs
Target resource(s):
-------------------
   OPS4J Pax Web - Samples - Hello World - HttpService (4.0.0.SNAPSHOT)

Required resource(s):
---------------------
   Apache ServiceMix :: Specs :: Activation API 1.4 (2.3.0.SNAPSHOT)
   OPS4J Pax Web - Jetty Bundle (4.0.0.SNAPSHOT)

Deploying...done.

The obr:start command uses the following syntax to identify the bundles: symbolic_name,version where version is optional. It means that you have to use the following command to deploy and start the wrapper core bundle with version 3.0.0:

karaf@root()> obr:start org.apache.karaf.wrapper.core,3.0.0

You can specify multiple bundles separated by space:

karaf@root()> obr:start org.apache.karaf.wrapper.core,3.0.0 org.apache.karaf.wrapper.command,3.0.0
...

JMX ObrMBean

On the JMX layer, Apache Karaf provides a MBean dedicated to the management of the OBR service: the ObrMBean.

The ObjectName to use is org.apache.karaf:type=obr,name=*.

Attributes

The Urls attribute provides the list of registered OBR repositories URLs.

The Bundles attribute provides a tabular data containing all bundles available on the registered OBR repositories.

Operations

addUrl(url) registers the OBR repository using the url to the repository.xml.
removeUrl(url) removes the OBR repository at the given url.
refreshUrl(url) refreshes the OBR repository at the given url.
deployBundle(name) deploys a bundle (and all bundles required to satisfy the requirements) using the OBR service. The bundles are not automatically started.
deployBundle(name, start, deployOptional) deploys a bundle (and all bundles required to satisfy the requirements) using the OBR service. If start is true, the bundles are automatically started. If deployOptional is true, even the optional requirements will be resolved by the OBR service (meaning installing more bundles to satisfy the optional requirements).

The name to identify a bundle uses the following syntax: symbolic_name,version where version is optional.

Apache Karaf Cave

In addition of being an OBR client, Apache Karaf can act as an OBR repositories server, thanks to Apache Karaf Cave.

See the Apache Karaf Cave for details.