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.12.0.SNAPSHOT activemq-camel | org.apache.activemq.activemq-camel | 5.12.0.SNAPSHOT activemq-karaf | activemq-karaf | 5.12.0.SNAPSHOT activemq-osgi | org.apache.activemq.activemq-osgi | 5.12.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/4.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/4.0.0/org.apache.karaf.wrapper.core-4.0.0.jar
size: 1281352
version: 4.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=4.0.0}
service:{service=org.apache.karaf.wrapper.WrapperService}
package:{package=org.apache.karaf.wrapper, version=4.0.0}
package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=4.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 4.0.0:
karaf@root()> obr:info org.apache.karaf.wrapper.core,4.0.0 ...
You can specific multiple bundles separated by space:
karaf@root()> obr:info org.apache.karaf.wrapper.core,4.0.0 org.apache.karaf.wrapper.command,4.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 4.0.0:
karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,4.0.0
You can specify multiple bundles separated by space:
karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core,4.0.0 org.apache.karaf.wrapper.command,4.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 (4.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/4.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/4.0.0/org.apache.karaf.wrapper.core-4.0.0.jar
size: 1281352
version: 4.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=4.0.0}
service:{service=org.apache.karaf.wrapper.WrapperService}
package:{package=org.apache.karaf.wrapper, version=4.0.0}
package:{package=org.apache.karaf.wrapper.management, uses:=javax.management, version=4.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 4.0.0:
karaf@root()> obr:deploy org.apache.karaf.wrapper.core,4.0.0
You can specify multiple bundles separated by space:
karaf@root()> obr:deploy org.apache.karaf.wrapper.core,4.0.0 org.apache.karaf.wrapper.command,4.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 4.0.0:
karaf@root()> obr:start org.apache.karaf.wrapper.core,4.0.0
You can specify multiple bundles separated by space:
karaf@root()> obr:start org.apache.karaf.wrapper.core,4.0.0 org.apache.karaf.wrapper.command,4.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 theurlto therepository.xml. -
removeUrl(url)removes the OBR repository at the givenurl. -
refreshUrl(url)refreshes the OBR repository at the givenurl. -
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. Ifstartistrue, the bundles are automatically started. IfdeployOptionalistrue, 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 http://karaf.apache.org/index/subprojects/cave.html for details.