• Created by Unknown User (isart_canyameres), last modified on 02 Aug, 2012

 

Steps to activate a bundle

In order for a bundle to be active in the shell:

1) Create bundle

A bundle is a group of Java classes and additional resources equipped with a detailed manifest file on all its contents, as well as additional services needed to give the included group of Java classes more sophisticated behaviors. Bundles are managed within an OSGi container.

From the developer point of view, a bundle is a project, with an associated pom.xml file. That pom.xml contains instructions for maven and its plug-ins (typically maven-bundle-plugin) to build the project as a bundle. That means, creating the artifact with its associated manifest.

If the building of a bundle succeeds, typically a jar file is created, containing compiled classes, the bundle MANIFEST.MF and other resources (e.g. the blueprint core.xml file from step 2).

It is important to check that MANIFEST.MF has an "Export-Package" section with all packages this bundle offers to other bundles. In the same way, a section named "Export-Service" tells the container what services are offered. Instruction for maven to build the manifest are given in the pom-xml file, through maven-bundle-plugin. More information on that plug-in is available on its website.

A bundle can be manually created (create required folders and files, edit pom.xml...) but there are tools that can do that for us. With karaf archetypes a bundle is generated automatically from the following information:

mvn archetype:generate \
    -DarchetypeGroupId=org.apache.karaf.archetypes \
    -DarchetypeArtifactId=karaf-blueprint-archetype \
    -DarchetypeVersion=2.2.5 \
    -DgroupId=com.mycompany \
    -DartifactId=com.mycompany.blueprint \
    -Dversion=1.0-SNAPSHOT \
    -Dpackage=com.mycompany.blueprint

In the example above, karaf-blueprint-archetype is used, generating a bundle with a blueprint file exporting a sample service. Please modify this file in order to export desired services, or remove it if no interaction with blueprint is required. Other archetypes are available, so check the Apache Karaf website for the appropriate one for each case.

 

2) Offer and consume services.

If your bundle should offer or consume services in the OSGi container, you should specify this within a blueprint core.xml file.

This file should be located inside your bundle, in src/main/resources/OSGI-INF/blueprint/core.xml. It will be included in the bundle jar when building it.

This is a typical xml file defining beans, services, and notification bindings. You may check already existent bundles for examples on its use.

More information about how to configure blueprint is available here.

This link is part of Fuse ESB guide for deploying into OSGi container containing detailed information on interacting with the OSGi container. It covers a wide range of topics, including steps 1 and 2 of this page. It is worth to look at (smile).

 

3) Add bundle to main project building process.

Add this bundle to its parent pom (modules section). This will cause this bundle to be build when building the parent.

Check for your bundle name in maven reactor when starting the build.

 

4) Add this bundle in OpenNaaS features.xml.

A feature is a group of bundles tied together providing certain functionality.

OpenNaaS features are defined in core/features/src/main/resources/features.xml file.

If your bundle extends an existent feature, you may add it to that one. Instead, if your bundle implements a new feature, it may be better to create a new feature with it.


5) Update platform to load new features.

If applicable, add new features to platform config file, to load them at boot time.

Platform config file is platform/src/main/filtered-resources/etc/org.apache.karaf.features.cfg.

Features included in "featuresBoot" section will be picked up and activated when platform loads. This way, those features functionality will be available to the user.

Please, check the feature your bundle belongs is included here.

 

6) Check all is correct

After building the whole project (or just your bundle, features and platform), when running the platform shell if you execute osgi:list command it should list the bundle among all the rest.

If it offers services using blueprint. Blueprint column for your bundle should display "Active".

 

References

Interesting references about pom files and OSGi bundles:

  • No labels