Once you've started deploying bundles into maven; the next step is to collect your bundles into feature repositories and make them available in your maven repository. (Don't get confused by the terminology - A OSGi feature repository is different than a maven repository)
Turns out it's fairly easy to get setup, since an OSGi feature repository is just an XML file. All you need to do is attach the XML file as an artifact to a maven project and you can deploy it and reference it from ServiceMix (the OSGi container I'm using; it might be possible in others, but I haven't tried).
Here's the process I use to deploy feature repositories:
1. First you need to create the features.xml file you will be deploying. See FuseSource's Documentation for a good overview.
It should look something like:
<?xml version="1.0" encoding="UTF-8" ?> <features> <feature name="tool-feature" version="${version}"> <bundle>mvn:us.justjohn.osgi/test-tools/1.1/jar/osgi</bundle> <bundle>mvn:us.justjohn.osgi/utilities/1.0/jar/osgi</bundle> </feature> </features>
Note the ${version}, we'll be using Maven's resource filtering to pull the version number in from the POM file.
2. Create a Maven project and put your features.xml file in src/main/resources. Use the following in your pom.xml file.
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>us.justjohn.osgi</groupId>
<artifactId>test-feature-repo</artifactId>
<packaging>pom</packaging>
<version>1.0-SNAPSHOT</version>
<name>Test ServiceMix Feature Collection</name>
<build>
<plugins>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>2.4.3</version>
<executions>
<execution>
<id>copy-resources</id>
<phase>validate</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${basedir}/target</outputDirectory>
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>true</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<executions>
<execution>
<id>attach-artifacts</id>
<phase>package</phase>
<goals>
<goal>attach-artifact</goal>
</goals>
<configuration>
<artifacts>
<artifact>
<file>target/features.xml</file>
<type>xml</type>
<classifier>features</classifier>
</artifact>
</artifacts>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
Let's break this down and see what's going on. First, the maven-resources-plugin is configured to filter all the resources in src/main/resources. This will allow you to put maven properties into your features.xml file. (In the example above I used ${version} to get the version from the POM)
Second, the build-helper-maven-plugin is configured to attach the filtered features.xml file as an artifact with the type xml and a classifier of features ( the classifier is optional, but makes the URL more readable and matches convention.)
This will result in a URL is ServiceMix like:
mvn:us.justjohn.osgi/test-feature-repo/1.0/xml/features
3. Deploy the feature to your maven repository:
$ mvn clean deploy
4. Load the feature repository URL in ServiceMix. (assuming you've already configured ServiceMix with you maven repository)
features:addUrl mvn:us.justjohn.osgi/test-feature-repo/1.0/xml/features
You can verify a successful load with features:listUrl, you should see the new URL listed. Now you're ready to load any features defined in the feature repository, in the example there's only one, "tool-feature". You can check that it's in the list of available features with:
features:list | grep "tool-feature"
You should see something like:
[uninstalled] [1.0 ] tool-feature ...
=========================================
http://fusesource.com/docs/esb/4.2/deploy_osgi/DeployFeatures-Create.html
Creating a Feature
Overview
Essentially, a feature is created by adding a new feature element to a special kind of XML file, known as a feature repository. To create a feature, perform the following steps:
- Create a custom feature repository.
- Add a feature to the custom feature repository.
- Add the local repository URL to the features service.
- Add dependent features to the feature.
- Add OSGi configurations to the feature.
Create a custom feature repository
If you have not already defined a custom feature repository, you can create one as follows. Choose a convenient location for the feature repository on your file system—for example, C:\Projects\features.xml—and use your favorite text editor to add the following lines to it:
<?xml version="1.0" encoding="UTF-8"?>
<features name="CustomRepository">
</features>
Where you can optionally specify a name for the repository, CustomRepository, by setting the name attribute. The default repository name is repo-0.
Add a feature to the custom feature repository
To add a feature to the custom feature repository, insert a new feature element as a child of the root features element. You must give the feature a name and you can list any number of bundles belonging to the feature, by inserting bundle child elements. For example, to add a feature named example-camel-bundle containing the single bundle, C:\Projects\camel-bundle\target\camel-bundle-1.0-SNAPSHOT.jar, add a feature element as follows:
<?xml version="1.0" encoding="UTF-8"?>
<features>
<feature name="example-camel-bundle">
<bundle>file:C:/Projects/camel-bundle/target/camel-bundle-1.0-SNAPSHOT.jar</bundle>
</feature>
</features>The contents of the bundle element can be any valid URL, giving the location of a bundle (see Appendix A). You can optionally specify a version attribute on the feature element, to assign a non-zero version to the feature (you can then specify the version as an optional argument to the features:install command).
To check whether the features service successfully parses the new feature entry, enter the following pair of console commands:
karaf@root> features:refreshUrl karaf@root> features:list ... [uninstalled] [0.0.0 ] example-camel-bundle repo-0 ...
The features:list command typically produces a rather long listing of features, but you should be able to find the entry for your new feature (in this case, example-camel-bundle) by scrolling back through the listing. The features:refreshUrl command forces the kernel to reread all the feature repositories: if you did not issue this command, the kernel would not be aware of any recent changes that you made to any of the repositories (in particular, the new feature would not appear in the listing).
To avoid scrolling through the long list of features, you can grep for the example-camel-bundle feature as follows:
karaf@root> features:list | grep example-camel-bundle [uninstalled] [0.0.0 ] example-camel-bundle repo-0
Where the grep command (a standard UNIX pattern matching utility) is built into the shell, so this command also works on Windows platforms.
Add the local repository URL to the features service
In order to make the new feature repository available to Apache Felix Karaf, you must add the feature repository using the features:addUrl console command. For example, to make the contents of the repository, C:\Projects\features.xml, available to the kernel, you would enter the following console command:
features:addUrl file:C:/Projects/features.xml
Where the argument to features:addUrl can be specified using any of the supported URL formats (see Appendix A).
You can check that the repository's URL is registered correctly by entering the features:listUrl console command, to get a complete listing of all registered feature repository URLs, as follows:
karaf@root> features:listUrl
mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.1.0-fuse-01-00/xml/features
mvn:org.apache.servicemix.camel/features/4.2.0-fuse-02-00/xml/features
file:C:/Projects/features.xml
mvn:org.apache.ode/ode-jbi-karaf/1.3.3-fuse-01-00/xml/features
mvn:org.apache.felix.karaf/apache-felix-karaf/1.2.0-fuse-01-00/xml/features
mvn:org.apache.servicemix/apache-servicemix/4.2.0-fuse-02-00/xml/features
Add dependent features to the feature
If your feature depends on other features, you can specify these dependencies by adding feature elements as children of the original feature element. Each child feature element contains the name of a feature on which the current feature depends. When you deploy a feature with dependent features, the dependency mechanism checks whether or not the dependent features are installed in the container. If not, the dependency mechanism automatically installs the missing dependencies (and any recursive dependencies).
For example, for the custom Apache Camel feature, example-camel-bundle, you can specify explicitly which standard Apache Camel features it depends on. This has the advantage that the application could now be successfully deployed and run, even if the OSGi container does not have the required features pre-deployed. For example, you can define the example-camel-bundle feature with Apache Camel dependencies as follows:
<?xml version="1.0" encoding="UTF-8"?>
<features>
<feature name="example-camel-bundle">
<bundle>file:C:/Projects/camel-bundle/target/camel-bundle-1.0-SNAPSHOT.jar</bundle>
<feature version="4.2.0-fuse-02-00">camel-core</feature>
<feature version="4.2.0-fuse-02-00">camel-spring-osgi</feature>
<feature version="4.2.0-fuse-02-00">servicemix-camel</feature>
</feature>
</features>Specifying the version attribute is optional. When present, it enables you to select the specified version of the feature.
Add OSGi configurations to the feature
If your application uses the OSGi Configuration Admin service, you can specify configuration settings for this service using the config child element of your feature definition. For example, to specify that the prefix property has the value, MyTransform, add the following config child element to your feature's configuration:
<?xml version="1.0" encoding="UTF-8"?>
<features>
<feature name="example-camel-bundle">
<config name="org.fusesource.fuseesb.example">
prefix=MyTransform
</config>
</feature>
</features>Where the name attribute of the config element specifies the persistent ID of the property settings (where the persistent ID acts effectively as a name scope for the property names). The content of the config element is parsed in the same way as a Java properties file.
The settings in the config element can optionally be overriden by the settings in the Java properties file located in the InstallDir/etc directory, which is named after the persistent ID, as follows:
InstallDir/etc/org.fusesource.fuseesb.example.cfg
As an example of how the preceding configuration properties can be used in practice, consider the following Spring XML file that accesses the OSGi configuration properties using Spring DM:
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ctx="http://www.springframework.org/schema/context"
xmlns:osgi="http://camel.apache.org/schema/osgi"
xmlns:osgix="http://www.springframework.org/schema/osgi-compendium" ...>
...
<bean id="myTransform" class="org.fusesource.fuseesb.example.MyTransform">
<property name="prefix" value="${prefix}"/>
</bean>
<osgix:cm-properties id="preProps" persistent-id="org.fusesource.fuseesb.example">
<prop key="prefix">DefaultValue</prop>
</osgix:cm-properties>
<ctx:property-placeholder properties-ref="preProps" />
</beans>When this Spring XML file is deployed in the example-camel-bundle bundle, the property reference, ${prefix}, is replaced by the value, MyTransform, which is specified by the config element in the feature repository.
