THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
4.6. Provisioning
ServiceMix Kernel 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.
Repositories
The xml repositories use the following Relax NG Compact syntax:
Repository schema
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:
<features>
<feature name="nmr" version="1.0.0">
<bundle>mvn:org.apache.servicemix.document/org.apache.servicemix.document/1.0.0</bundle>
<bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.api/1.0.0</bundle>
<bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.core/1.0.0</bundle>
<bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.osgi/1.0.0</bundle>
<bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.spring/1.0.0</bundle>
<bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.commands/1.0.0</bundle>
<bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.management/1.0.0</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.
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:
<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, ServiceMix Kernel 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:
<bundle>mvn:org.apache.servicemix.nmr/org.apache.servicemix.nmr.api/1.0.0-m2</bundle>
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:
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:
karaf@root:/> config/edit org.ops4j.pax.url.mvn
karaf@root:/> config/proplist
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
karaf@root:/> config/propset org.ops4j.pax.url.mvn.repositories http://www.example.org/repo
karaf@root:/> config/update
By default, snapshots are disable. To enable an URL for snapshots append @snapshots. For example
http://www.example.org/repo@snapshots
Repositories on the local are supported through file:/ URLs
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:
<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:
<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-instanceId, where servicePid is the PID of the ManagedServiceFactory and instanceId is a label used to uniquely identify a particular service instance.
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 support for the Configuration Admin service, as in the following example, but using plain OSGi APIs will of course work the same way:
<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 ServiceMix Kernel. 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.
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
ServiceMix Kernel maintains a persistent list of these repositories so that if you add one URL and restart the Kernel, 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
features/install features/uninstall features/list
Examples
features/addUrl mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.0.0-m2/xml/features features/install nmr
Service configuration
A simple configuration file located in [SMX4KNL:kernel]/etc/org.apache.servicemix.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 a ServiceMix Kernel distribution which includes pre-installed features. Such a process is detailed in the 6.2. Building custom distributions section.