...
anchortop
4.6. Provisioning
Karaf provides a simple, yet flexible, way to provision applications or "features". Such a mechanism is mainly provided by a set of commands available in the features
shell. The provisioning system uses xml "repositories" that define a set of features.
Commands
Repositories
The xml features repositories use the following Relax NG Compact syntax:
Code Block | ||
---|---|---|
| ||
element features {
element repository { text }*
element feature {
attribute name { text },
attribute version { text },
element feature {
attribute version { text },
text
}*,
element config {
attribute name { text },
text
}*,
element bundle { text }*
}*
}
|
Here is an example of such a repository:
Code Block | ||
---|---|---|
| ||
<features>
<feature name="spring" version="2.5.6.SEC01">
<bundle>mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.aopalliance/1.0_1</bundle>
<bundle>mvn:org.springframework/spring-core/2.5.6.SEC01</bundle>
<bundle>mvn:org.springframework/spring-beans/2.5.6.SEC01</bundle>
<bundle>mvn:org.springframework/spring-aop/2.5.6.SEC01</bundle>
<bundle>mvn:org.springframework/spring-context/2.5.6.SEC01</bundle>
<bundle>mvn:org.springframework/spring-context-support/2.5.6.SEC01</bundle>
</feature>
</features>
|
A repository includes a list of feature
elements, each one representing an application that can be installed. The feature is identified by its name
which must be unique amongst all the repositories used and consists of a set of bundles that need to be installed along with some optional dependencies on other features and some optional configurations for the Configuration Admin OSGi service.
References to features define in other repositories are allow and can be achieved by adding a list of repository.
...
<features>
<repository>mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.2.0/xml/features</repository>
<repository>mvn:org.apache.camel.karaf/apache-camel/2.2.0/xml/features</repository>
<repository>mvn:org.apache.felix.karaf/apache-felix-karaf/1.4.0/xml/features</repository>
...
Repository management
The following commands can be used to manage the list of descriptors known by Karaf. They use URLs pointing to features descriptors. These URLs can use any protocol known to the Apache Karaf, the most common ones being http, file and mvn.
...
Karaf maintains a persistent list of these repositories so that if you add one URL and restart Karaf, the features will still be available.
The refreshUrl
command is mostly used when developing features descriptors: when changing the descriptor, it can be handy to reload it in the Kernel without having to restart it or to remove then add again this URL.
Some Featue Repositories you might want to add
Project | Feature Repository URL |
---|---|
Camel | mvn:org.apache.camel.karaf/apache-camel/2.6.0/xml/features |
ActiveMQ | mvn:org.apache.activemq/activemq-karaf/5.4.2/xml/features |
If you know some more URLs feel free to add them here
Features management
...
Examples
1. Install features using mvn handler
...
2. Use file handler to deploy features file
...
Remark : The path is relative to the Apache Karaf installation directory
3. Deploy bundles from file system without using maven
As we can use file:// as protocol handler to deploy bundles, you can use the following syntax to deploy bundles when they are
located in a directory which is not available using maven
...
Remark : The path is relative to the Apache Karaf installation directory
Service configuration
A simple configuration file located in [FELIX:karaf]/etc/org.apache.karaf.features.cfg
can be modified to customize the behavior when starting the Kernel for the first time.
This configuration file contains two properties:
featuresBoot
: a comma separated list of features to install at startupfeaturesRepositories
: a comma separated list of feature repositories to load at startup
This configuration file is of interest if you plan to distribute Apache Karaf distribution which includes pre-installed features. Such a process is detailed in the 6.2. Custom distributions section.
Repositories
The xml features repositories use the following Relax NG Compact syntax:
...
Here is an example of such a repository:
...
A repository includes a list of feature
elements, each one representing an application that can be installed. The feature is identified by its name
which must be unique amongst all the repositories used and consists of a set of bundles that need to be installed along with some optional dependencies on other features and some optional configurations for the Configuration Admin OSGi service.
References to features define in other repositories are allow and can be achieved by adding a list of repository.
...
Warning |
---|
Be carefull when you define them as there is a risk of 'cycling' dependencies. |
Remark : By default, all the features defined in a repository are not installed at the launch of Apache Karaf (see section hereafter 'h2. Service configuration' for more info).
Bundles
The main information provided by a feature is the set of OSGi bundles that defines the application. Such bundles are URLs pointing to the actual bundle jars. For example, one would write the following definition:
Code Block | ||
---|---|---|
| ||
<bundle>http://repo1.maven.org/maven2/org/apache/servicemix/nmr/org.apache.servicemix.nmr.api/1.0.0-m2/org.apache.servicemix.nmr.api-1.0.0-m2.jar</bundle>
|
Doing this will make sure the above bundle is installed while installing the feature.
However, Karaf provides several URL handlers, in addition to the usual ones (file, http, etc...). One of these is the maven URL handler, which allow reusing maven repositories to point to the bundles.
Maven URL Handler
The equivalent of the above bundle would be:
...
In addition to being less verbose, the maven url handlers can also resolve snapshots and can use a local copy of the jar if one is available in your maven local repository.
The org.ops4j.pax.url.mvn
bundle resolves mvn
URLs. This flexible tool can be configured through the configuration service. For example, to find the current repositories type:
Code Block |
---|
karaf@root:/> config:list
...
----------------------------------------------------------------
Pid: org.ops4j.pax.url.mvn
BundleLocation: mvn:org.ops4j.pax.url/pax-url-mvn/0.3.3
Properties:
service.pid = org.ops4j.pax.url.mvn
org.ops4j.pax.url.mvn.defaultRepositories = file:/opt/development/karaf/assembly/target/apache-felix-karaf-1.2.0-SNAPSHOT/system@snapshots
org.ops4j.pax.url.mvn.repositories = http://repo1.maven.org/maven2,
http://people.apache.org/repo/m2-snapshot-repository<at:var at:name="snapshots" />noreleases,
http://repository.ops4j.org/maven2,
http://svn.apache.org/repos/asf/servicemix/m2-repo
below = list of repositories and even before the local repository
|
The repositories checked are controlled by these configuration properties.
For example, org.ops4j.pax.url.mvn.repositories
is a comma separate list of repository URLs specifying those remote repositories to be checked. So, to replace the defaults with a new repository at http://www.example.org/repo
on the local machine:
...
Be carefull when you define them as there is a risk of 'cycling' dependencies.
...
Remark : By default, all the features defined in a repository are not installed at the launch of Apache Karaf (see section hereafter 'h2. Service configuration' for more info).
Bundles
The main information provided by a feature is the set of OSGi bundles that defines the application. Such bundles are URLs pointing to the actual bundle jars. For example, one would write the following definition:
...
Doing this will make sure the above bundle is installed while installing the feature.
However, Karaf provides several URL handlers, in addition to the usual ones (file, http, etc...). One of these is the maven URL handler, which allow reusing maven repositories to point to the bundles.
Maven URL Handler
The equivalent of the above bundle would be:
...
In addition to being less verbose, the maven url handlers can also resolve snapshots and can use a local copy of the jar if one is available in your maven local repository.
The org.ops4j.pax.url.mvn
bundle resolves mvn
URLs. This flexible tool can be configured through the configuration service. For example, to find the current repositories type:
...
The repositories checked are controlled by these configuration properties.
For example, org.ops4j.pax.url.mvn.repositories
is a comma separate list of repository URLs specifying those remote repositories to be checked. So, to replace the defaults with a new repository at http://www.example.org/repo
on the local machine:
...
By default, snapshots are disable. To enable an URL for snapshots append @snapshots. For example
Code Block |
---|
http://www.example.org/repo@snapshots
|
Repositories on the local are supported through file:/
URLs
Bundle start-level
By default, the bundles deployed through the feature mechanism will have a start-level equals to the value defined in the configuration file config.properties
with the variable karaf.startlevel.bundle=60
. This value can be changed using the xml attribute start-level.
Code Block |
---|
<feature name='my-project' version='1.0.0'>
<feature version='2.4.0'>camel-spring</feature>
<bundle start-level='80'>mvn:com.mycompany.myproject/myproject-dao</bundle>
<bundle start-level='85'>mvn:com.mycompany.myproject/myproject-service</bundle>
<bundle start-level='85'>mvn:com.mycompany.myproject/myproject-camel-routing</bundle>
</feature>
|
The advantage to define the start-level of a bundle is that you can deploy all your bundles including those of the project with the 'infrastructure' bundles required (e.g : camel, activemq)
at the same time and you will have the guaranty when you use Spring Dynamic Module (to register service through OSGI service layer), Blueprint that by example
Spring context will not be created without all the required services installed.
Dependant features
Dependant features are usefull when a given feature depends on another feature to be installed. Such a dependency can be expressed easily in the feature definition:
Code Block | ||
---|---|---|
| ||
<feature name="jbi">
<feature>nmr</feature>
...
</feature>
|
The effect of such a dependency is to automatically install the required nmr
feature when the jbi
feature will be installed.
Configurations
The configuration section allows to deploy configuration for the OSGi Configuration Admin service along a set of bundles.
Here is an example of such a configuration:
Code Block | ||
---|---|---|
| ||
<config name="com.foo.bar">
myProperty = myValue
</config>
|
The name
attribute of the configuration
element will be used as the ManagedService PID for the configuration set in the Configuration Admin service. When using a ManagedServiceFactory, the name
attribute is servicePid-aliasId, where servicePid is the PID of the ManagedServiceFactory and aliasId is a label used to uniquely identify a particular service (an alias to the factory generated service PID).
Deploying such a configuration has the same effect than dropping a file named com.foo.bar.cfg
into the etc
folder.
The content of the configuration
element is set of properties parsed using the standard java property mechanism.
Such configuration as usually used with Spring-DM or Blueprint support for the Configuration Admin service, as in the following example, but using plain OSGi APIs will of course work the same way:
Code Block | ||
---|---|---|
| ||
<bean ...>
<property name="propertyName" value="${myProperty}" />
</bean>
<osgix:cm-properties id="cmProps" persistent-id="com.foo.bar">
<prop key="myProperty">myValue</prop>
</osgix:cm-properties>
<ctx:property-placeholder properties-ref="cmProps" />
|
For more informations about using the Configuration Admin service in Spring-DM, see the Spring-DM documentation.
Commands
Repository management
The following commands can be used to manage the list of descriptors known by Karaf. They use URLs pointing to features descriptors. These URLs can use any protocol known to the ServiceMix Kernel, the most common ones being http, file and mvn.
Code Block |
---|
features:addUrl Add a list of repository URLs to the features service
features:removeUrl Remove a list of repository URLs from the features service
features:listUrl Display the repository URLs currently associated with the features service.
features:refreshUrl Reload the repositories to obtain a fresh list of features
|
Karaf maintains a persistent list of these repositories so that if you add one URL and restart Karaf, the features will still be available.
The refreshUrl
command is mostly used when developing features descriptors: when changing the descriptor, it can be handy to reload it in the Kernel without having to restart it or to remove then add again this URL.
Features management
Code Block |
---|
features:install
features:uninstall
features:list
|
Examples
1. Install features using mvn handler
Code Block |
---|
features:addUrl mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.0.0-m2/xml/features
features:install nmr
|
2. Use file handler to deploy features file
Code Block |
---|
features:addUrl file:base/features/features.xml
|
Remark : The path is relative to the Apache Karaf installation directory
3. Deploy bundles from file system without using maven
As we can use file:// as protocol handler to deploy bundles, you can use the following syntax to deploy bundles when they are
located in a directory which is not available using maven
...
<features>
<feature name="spring-web" version="2.5.6.SEC01">
<bundle>file:base/bundles/spring-web-2.5.6.SEC01.jar</bundle>
</feature>
</features>
Remark : The path is relative to the Apache Karaf installation directory
Service configuration
Wiki Markup |
---|
A simple configuration file located in {{\[FELIX:karaf\]/etc/org.apache.karaf.features.cfg}} can be modified to customize the behavior when starting the Kernel for the first time.
This configuration file contains two properties: |
featuresBoot
: a comma separated list of features to install at startupfeaturesRepositories
: a comma separated list of feature repositories to load at startup
This configuration file is of interest if you plan to distribute Apache Karaf distribution which includes pre-installed features. Such a process is detailed in the 6.2. Building custom distributions section.
Wiki Markup |
---|
{scrollbar} |
...
By default, snapshots are disable. To enable an URL for snapshots append @snapshots. For example
...
Repositories on the local are supported through file:/
URLs
Bundle start-level
Available since Karaf 2.0
By default, the bundles deployed through the feature mechanism will have a start-level equals to the value defined in the configuration file config.properties
with the variable karaf.startlevel.bundle=60
. This value can be changed using the xml attribute start-level.
...
The advantage to define the start-level of a bundle is that you can deploy all your bundles including those of the project with the 'infrastructure' bundles required (e.g : camel, activemq)
at the same time and you will have the guaranty when you use Spring Dynamic Module (to register service through OSGI service layer), Blueprint that by example
Spring context will not be created without all the required services installed.
Bundle 'stop/start'
Available since Karaf 2.0
The OSGI specification allows to install a bundle without starting it. To use this functionality, simply add the following attribute in your <bundle> definition
...
Dependent features
Dependent features are useful when a given feature depends on another feature to be installed. Such a dependency can be expressed easily in the feature definition:
...
The effect of such a dependency is to automatically install the required nmr
feature when the jbi
feature will be installed.
Configurations
The configuration section allows to deploy configuration for the OSGi Configuration Admin service along a set of bundles.
Here is an example of such a configuration:
...
The name
attribute of the configuration
element will be used as the ManagedService PID for the configuration set in the Configuration Admin service. When using a ManagedServiceFactory, the name
attribute is servicePid-aliasId, where servicePid is the PID of the ManagedServiceFactory and aliasId is a label used to uniquely identify a particular service (an alias to the factory generated service PID).
Deploying such a configuration has the same effect than dropping a file named com.foo.bar.cfg
into the etc
folder.
The content of the configuration
element is set of properties parsed using the standard java property mechanism.
Such configuration as usually used with Spring-DM or Blueprint support for the Configuration Admin service, as in the following example, but using plain OSGi APIs will of course work the same way:
...
There may also be cases where you want to make the properties from multiple configuration files available to your bundle context. This is something you may want to do if you have a multi-bundle application where there are application properties used by multiple bundles, and each bundle has its own specific properties. In that case, <ctx:property-placeholder>
won't work as it was designed to make only one configuration file available to a bundle context.
To make more than one configuration file available to your bundle-context you would do something like this:
...
In this example, we are using SpringDM with osgi as the primary namespace. Instead of using ctx:context-placeholder we are using the "PropertyPlaceholderConfig" class. Then we are passing in a beans array and inside of that array is where we set our osgix:cm-properties elements. This element "returns" a properties bean.
For more informations about using the Configuration Admin service in Spring-DM, see the Spring-DM documentation.
...