OSGi Usage in DDF

OSGi Service Registry

DDF uses resource injection to retrieve and register services to the OSGi registry. There are many resource injection frameworks that are used to complete these operations. Blueprint and Spring DM are both used by DDF. There are many tutorials and guides available on the Internet for both of these frameworks. Refer to the Additional Resources section for details not covered in this guide. Links to some of these guides are given in the External Links area of this section.

Spring DM - Retrieving a Service instance

Spring DM example of retrieving and injecting Services

1  <beans xmlns="http://www.springframework.org/schema/beans"
2   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
3   xmlns:osgi="http://www.springframework.org/schema/osgi">
4
5   <osgi:reference id="ddfCatalogFramework" interface="ddf.catalog.CatalogFramework" />
6 
7   <bean class="my.sample.NiftyEndpoint">
8      <constructor-arg ref="ddfCatalogFramework" />
9   </bean>
10 </beans>

Line #	Action
5	Retrieves a Service from the Registry
8	Instantiates a new object, injecting the retrieved Service as a constructor argument

Blueprint - Retrieving a Service instance

Blueprint example of retrieving and injecting Services

1  <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
2  
3   <reference id="ddfCatalogFramework" interface="ddf.catalog.CatalogFramework" /> 
4 
5   <bean class="my.sample.NiftyEndpoint" >
6      <argument ref="ddfCatalogFramework" />
7   </bean>
8 
9  </blueprint>

Line #	Action
3	Retrieves a Service from the Registry
6	Instantiates a new object, injecting the retrieved Service as a constructor argument

Blueprint - Registering a Service into the Registry

Creating a bean and registering it into the Service Registry

1  <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
2
3   <bean id="transformer" class="my.sample.NiftyTransformer"/>
4
5   <service ref="transformer" interface="ddf.catalog.transform.QueryResponseTransformer" />
6
7  </blueprint>

Line #	Action
3	Instantiates a new object
5	Registers the object instance created in Line 3 as a service that implements the `ddf.catalog.transform.QueryResponseTransformer` interface

Packaging Capabilities as Bundles

Services and code are physically deployed to DDF by using bundles. The bundles within DDF are created using the maven bundle plug-in. Bundles are essentially Java JAR files that have additional metadata in the MANIFEST.MF that is relevant to an OSGi container.

Alternative bundle creation methods

Using Maven is not necessary to create bundles. Alternative tools exist, and OSGi manifest files can also be created by hand although hand editing should be avoided by most developers.

See external links (below) for resources that give in-depth guides on creating bundles.

Creating a Bundle

Bundle Development Recommendations:

Avoid creating bundles by hand or editing a manifest file. Many tools exist for creating bundles, notably the Maven Bundle plugin, which handle the details of OSGi configuration and automate the bundling process including generation of the manifest file.
Always make a distinction on which imported packages are optional or required. Requiring every package when not necessary can cause an unnecessary dependency ripple effect among bundles.

Maven Bundle Plugin

Below is a code snippet from a Maven pom.xml for creating an OSGi Bundle using the Maven Bundle Plugin.

Maven pom.xml

...
<packaging>bundle</packaging>
...
<build>
...
  <plugin>
    <groupId>org.apache.felix</groupId>
    <artifactId>maven-bundle-plugin</artifactId>
    <configuration>
      <instructions>
        <Bundle-Name>${project.name}</Bundle-Name>
        <Export-Package />
        <Bundle-SymbolicName>${project.groupId}.${project.artifactId}</Bundle-SymbolicName>
        <Import-Package>
          ddf.catalog,
          ddf.catalog.*
        </Import-Package>
      </instructions>
    </configuration>
  </plugin>
...
</build>
...

Deploying a Bundle

A bundle is typically installed in two ways:

As a feature.
Hot deployed in the /deploy directory.

The fastest way during development to deploy a created bundle is to copy it to the /deploy directory of a running DDF. This directory checks for new bundles and deploys them immediately. According to Karaf documentation, "Karaf supports hot deployment of OSGi bundles by monitoring JAR files inside the [home]/deploy directory. Each time a JAR is copied in this folder, it will be installed inside the runtime. It can be updated or deleted and changes will be handled automatically. In addition, Karaf also supports exploded bundles and custom deployers (Blueprint and Spring DM are included by default)." Once deployed, the bundle should come up in the Active state if all of the dependencies were properly met. When this occurs, the service is available to be used.

Verifying Bundle State

To verify if a bundle is deployed and running, go to the running command console and view the status.

Execute the list command.
If the name of the bundle is known, the list command can be piped to the grep command to quickly find the bundle.

The example below shows how to verify if the CAB Client is deployed and running.

Verifying with grep

ddf@local>list | grep -i cab
[ 162] [Active    ] [       ] [  ] [ 80] DDF :: Registry :: CAB Client (2.0.0)

The state is Active meaning that the bundle is ready for program execution.

Additional Resources

Blueprint

Spring DM
- http://www.springsource.org/osgi

Lessons Learned from it-agile (PDF)
- http://www.martinlippert.org/events/OOP2010-OSGiLessonsLearned.pdf

Creating Bundles
- http://blog.springsource.com/2008/02/18/creating-osgi-bundles/
Bundle states
- http://static.springsource.org/osgi/docs/1.2.1/reference/html/bnd-app-ctx.html