You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2013/12/07 15:22:05 UTC
svn commit: r1548916 - in /karaf/trunk/manual/src/main/webapp:
_navigation.conf manual.conf users-guide/index.conf
users-guide/instances.conf users-guide/obr.conf
Author: jbonofre
Date: Sat Dec 7 14:22:05 2013
New Revision: 1548916
URL: http://svn.apache.org/r1548916
Log:
[KARAF-2511] Add the OBR section in the user guide
Added:
karaf/trunk/manual/src/main/webapp/users-guide/obr.conf
Modified:
karaf/trunk/manual/src/main/webapp/_navigation.conf
karaf/trunk/manual/src/main/webapp/manual.conf
karaf/trunk/manual/src/main/webapp/users-guide/index.conf
karaf/trunk/manual/src/main/webapp/users-guide/instances.conf
Modified: karaf/trunk/manual/src/main/webapp/_navigation.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/_navigation.conf?rev=1548916&r1=1548915&r2=1548916&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/_navigation.conf (original)
+++ karaf/trunk/manual/src/main/webapp/_navigation.conf Sat Dec 7 14:22:05 2013
@@ -19,7 +19,7 @@ h3. [Users Guide|/users-guide/index]
- [KAR|/users-guide/kar]
- [Instances|/users-guide/instances]
- [Security|/users-guide/security]
-- OBR
+- [OBR|/users-guide/obr]
- Enterprise
-- [WebContainer (JSP/Servlet)|/users-guide/webcontainer]
-- Naming (JNDI)
Modified: karaf/trunk/manual/src/main/webapp/manual.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/manual.conf?rev=1548916&r1=1548915&r2=1548916&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/manual.conf (original)
+++ karaf/trunk/manual/src/main/webapp/manual.conf Sat Dec 7 14:22:05 2013
@@ -48,6 +48,7 @@ h1. Users Guide
{include:users-guide/kar}
{include:users-guide/instances}
{include:users-guide/security}
+{include:users-guide/obr}
{include:users-guide/enterprise}
{include:users-guide/webcontainer}
{include:users-guide/failover}
Modified: karaf/trunk/manual/src/main/webapp/users-guide/index.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/index.conf?rev=1548916&r1=1548915&r2=1548916&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/index.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/index.conf Sat Dec 7 14:22:05 2013
@@ -14,7 +14,7 @@ h1. Users Guide
* [KAR|kar]
* [Instances|instances]
* [Security|security]
-* OBR
+* [OBR|obr]
* [Enterprise|enterprise]
** [WebContainer (JSP/Servlet)|webcontainer]
** Naming (JNDI)
Modified: karaf/trunk/manual/src/main/webapp/users-guide/instances.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/instances.conf?rev=1548916&r1=1548915&r2=1548916&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/instances.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/instances.conf Sat Dec 7 14:22:05 2013
@@ -329,7 +329,7 @@ OPTIONS
h2. JMX InstanceMBean
-On the JMX layer, you have a MBean dedicated to the management of the instances.
+On the JMX layer, you have a MBean dedicated to the management of the instances: the InstanceMBean.
The ObjectName to use is {{org.apache.karaf:type=instance,name=*}}.
Added: karaf/trunk/manual/src/main/webapp/users-guide/obr.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/obr.conf?rev=1548916&view=auto
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/obr.conf (added)
+++ karaf/trunk/manual/src/main/webapp/users-guide/obr.conf Sat Dec 7 14:22:05 2013
@@ -0,0 +1,286 @@
+h1. OBR
+
+The goal of OBR (OSGi Bundle Repository) is:
+
+1. to simplify deploying and using bundles
+2. 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:
+
+{code}
+karaf@root()> feature:install obr
+{code}
+
+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.
+
+h2. 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.
+
+h2. Commands
+
+h3. {{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:
+
+{code}
+karaf@root()> obr:url-add file:///user/.m2/repository/repository.xml
+{code}
+
+h3. {{obr:url-list}}
+
+The {{obr:url-list}} command lists the OBR repository (with URL) registered in the OBR service:
+
+{code}
+karaf@root()> obr:url-list
+Index | OBR URL
+---------------------------------------------------------
+0 | file:/user/.m2/repository/repository.xml
+{code}
+
+h3. {{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:
+
+{code}
+karaf@root()> obr:url-refresh
+{code}
+
+You can refresh only one repository by specifying the URL as argument:
+
+{code}
+karaf@root()> obr:url-refresh file:/user/.m2/repository/repository.xml
+{code}
+
+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:
+
+{code}
+karaf@root()> obr:url-refresh -i 0
+{code}
+
+h3. {{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:
+
+{code}
+karaf@root()> obr:url-remove file:/user/.m2/repository/repository.xml
+{code}
+
+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:
+
+{code}
+karaf@root()> obr:url-remove -i 0
+{code}
+
+h3. {{obr:list}}
+
+The {{obr:list}} command lists all bundles available on the registered OBR repositories:
+
+{code}
+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
+...
+{code}
+
+h3. {{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:
+
+{code}
+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}
+{code}
+
+h3. {{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:
+
+{code}
+karaf@root()> obr:source /tmp org.apache.karaf.wrapper.core
+{code}
+
+h3. {{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:
+
+{code}
+karaf@root()> obr:resolve package=org.apache.karaf.wrapper
+Required resource(s):
+---------------------
+ Apache Karaf :: Wrapper :: Core (3.0.0)
+{code}
+
+h3. {{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:
+
+{code}
+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}
+{code}
+
+h3. {{obr:deploy}}
+
+The {{obr:deploy}} command installs a bundle from the OBR repository, including all bundles required to satisfy the bundle requirements.
+
+{code}
+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.
+{code}
+
+By default, the bundles are just installed, not started. You can use the {{-s}} option to start the bundles.
+
+h2. {{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.
+
+h2. 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=*}}.
+
+h3. 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.
+
+h3. 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).
+
+h2. 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 sub-project|http://karaf.apache.org/index/subprojects/cave.html] for details.
\ No newline at end of file