Fuse ESB - Managing OSGi Dependencies

Overview

This section explains how to set up a Maven project for a consumer bundle.

The hello-consumer bundle exemplifies a consumer bundle, which imports OSGi services and accesses the services through the relevant API packages. This is the bundle that drives the sample application and, therefore, it relies on a blueprint lifecycle callback (through the blueprint bean element's init-method attribute) to initiate processing.

	Note
	Being a consumer is just a role, not an absolute category, so you will commonly come across bundles that behave both as a consumer and a provider. In the current example, however, `hello-consumer` behaves as a pure consumer.

Directory structure

The hello-consumer bundle has the following directory structure:

hello-consumer/
  |
  \--src/
     |
     \--main/
     |  |
     |  \--java/
     |  |  |
     |  |  \--org/fusesource/example/hello/consumer/
     |  |     |
     |  |     \--ConsumeHello.java
     |  |
     |  \--resources/
     |     |
     |     \--OSGI-INF/blueprint/
     |        |
     |        \--client.xml
     |   
     \--test/

The org.fusesource.example.hello.consumer package is public and all of its classes and interfaces are exported from the bundle. It would not matter, however, if you made this package private instead, because it is not needed by any other bundles.

The src/main/resources/OSGI-INF/blueprint directory contains a single blueprint file, client.xml. Any file matching the pattern, *.xml, in this directory is assumed to be a blueprint configuration file.

Sample consumer code

The hello-consumer bundle effectively drives the sample application, obtaining references to the HelloBoston and HelloParis OSGi services, and then invoking methods on these services to obtain localised greetings and times.

The hello-consumer bundle contains the class, ConsumeHello, which is a client of the OSGi services, HelloBoston and HelloParis. To gain access to the OSGi services, ConsumeHello defines the setter methods, getHelloBoston() and getHelloParis(), and relies on the blueprint framework to inject the references. The entry point is the init() method, which gets invoked after the ConsumeHello bean is created and injected with the service references. The ConsumeHello class is defined as follows:

// Java
package org.fusesource.example.hello.consumer;

import org.fusesource.example.hello.boston.HelloBoston;
import org.fusesource.example.hello.paris.HelloParis;

public class ConsumeHello {
    protected HelloBoston helloBoston = null;
    protected HelloParis helloParis = null;

    /**
     * @param args
     */
    public static void main(String[] args) {
        // TODO Auto-generated method stub

    }
    
    public void init() {
        if (helloBoston==null || helloParis==null) {
            System.out.println("Initialization failed. Injected objects are null.");
            return;
        }
        
        String enGreeting = helloBoston.getGreeting();
        String bostonTime = helloBoston.getLocalTime().getLocalTime();
        System.out.println("Boston says:" + enGreeting + " at " + bostonTime);
        
        String frGreeting = helloParis.getGreeting();
        String parisTime = helloParis.getLocalTime().getLocalTime();
        System.out.println("Paris says:" + frGreeting + " at " + parisTime);
    }

    public HelloBoston getHelloBoston() {
        return helloBoston;
    }

    public void setHelloBoston(HelloBoston helloBoston) {
        this.helloBoston = helloBoston;
    }

    public HelloParis getHelloParis() {
        return helloParis;
    }

    public void setHelloParis(HelloParis helloParis) {
        this.helloParis = helloParis;
    }
    
}

Access OSGi service

The ConsumeHello class needs to obtain a reference to the HelloBoston service and a reference to the HelloParis service. Use the reference element to create proxies for the HelloBoston service and for the HelloParis service. Use the bean element to create a ConsumeHello instance and inject the helloBoston and helloParis proxies.

The ConsumeHello bean also requires an entry point to initiate processing. By setting the bean element's init-method attribute to init, you ensure that the blueprint framework calls the ConsumeHello.init() method after all of the bean's properties have been injected.

For example, the blueprint file, OSGI-INF/blueprint/client.xml, has the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

    <reference id="helloBoston"
        interface="org.fusesource.example.hello.boston.HelloBoston"/>

    <reference id="helloParis"
        interface="org.fusesource.example.hello.paris.HelloParis"/>

    <bean id="client"
          class="org.fusesource.example.hello.consumer.ConsumeHello"
          init-method="init">
        <property name="helloBoston" ref="helloBoston"/>
        <property name="helloParis" ref="helloParis"/>
    </bean>

</blueprint>

<instructions>
  <Bundle-SymbolicName>${project.groupId}.${project.artifactId}</Bundle-SymbolicName>
  <Import-Package>*</Import-Package>
  <Export-Package>
    !${project.groupId}*.impl*,
    !${project.groupId}*.internal*,
	${project.groupId}.hello.consumer*;version=${project.version}
  </Export-Package>
</instructions>

Generated MANIFEST.MF file

When you build the bundle using Maven, the Maven bundle plug-in automatically generates the following MANIFEST.MF file:

Manifest-Version: 1.0
Built-By: JBLOGGS
Created-By: Apache Maven Bundle Plugin
Import-Package: org.fusesource.example.hello.boston;version="[1.0,2)",
 org.fusesource.example.hello.paris;version="[1.0,2)",org.fusesource.e
 xample.time;version="[1.0,2)",org.osgi.service.blueprint;version="[1.
 0.0,2.0.0)"
Bnd-LastModified: 1296826333723
Export-Package: org.fusesource.example.hello.consumer;uses:="org.fuses
 ource.example.time,org.fusesource.example.hello.paris,org.fusesource.
 example.hello.boston";version="1.0"
Bundle-Version: 1.0.0
Bundle-Name: hello-consumer
Build-Jdk: 1.5.0_08
Bundle-ManifestVersion: 2
Bundle-SymbolicName: org.fusesource.example.hello-consumer
Tool: Bnd-1.15.0
Import-Service: org.fusesource.example.hello.boston.HelloBoston,org.fu
 sesource.example.hello.paris.HelloParis

The Import-Package header imports the external package dependencies—for example, org.fusesource.example.hello.boston.

The Export-Package header exports the package, org.fusesource.example.hello.consumer. In this case, however, the export is not really needed and the package could have been declared private instead (for example, using the Private-Package instruction).

The Import-Service header declares the OSGi services accessed by this bundle. The services are accessed respectively through the HelloBoston interface and through the HelloParis interface.