Lightsabre - Getting Started

This small tutorial introduces the basic concept of the integration approach for asynchronous messaging inside OSGi used by this project. At the end of this tutorial you will have created an application which forwards messages from one OSGi container to another one via an ActiveMQ message broker.

The functionality of the application which is implemented during this tutorial is shown in the figure below. The publishing OSGi container contains a bundle which shows a swing dialog which lets you enter a text message. When you hit the send button, your message is forwarded to a messaging topic on the ActiveMQ message broker which will relay the message to all consumers listening for messages on this topic. The Consuming OSGi container contains a bundle which waits for messages from the messaging topic to output them on the command line.

EDS Concept

This Lightsabre project uses the OSGi EventAdmin to integrate the basic functionality of a messaging system into OSGi. Due to this, both the message consumer and producer bundle will communicate with the EventAdmin by sending and receiving events which will be delivered to or received from the message broker in form of messages. The forwarding is realized by the Event Distribution System (EDS) bundle. The configuration which defines which messaging system is used, which messaging topic and which event topic are relevant is applied to the EDS by the OSGi ConfigurationAdmin. The project also provides a bundle scanner which searches for configuration files in installed bundles and applies these configuration properties to the Configuration Admin.

Requirements

Obtaining the Event Distribution System

On the build page you can find some information on how to obtain and build the source code. After the successful build of the EDS and its components you will find the generated bundles in the target directories of each component. For this demo the following bundles are needed:

Event Distribution System
ActiveMQ Wrapper
- Dependencies (can be found in the dependencies directory):
  - Apache ActiveMQ client libraries ( activemq-core-5.2.0.jar )
  - geronimo-jms_1.1_spec-1.1.1.jar
  - geronimo-j2ee-management_1.1_spec-1.0.1.jar
  - com.springsource.org.apache.commons.logging-1.1.1.jar
Bundle Scanner

Runtime Environment

Besides those components you need an OSGi environment with an implementation of the following services:

Event Admin
Configuration Admin
Declarative Services
(optional) Luminis provides a bundle which enables the user easy access to the configuration data managed by the ConfigurationAdmin from the osgi shell. The Bundle can be downloaded from https://opensource.luminis.net/wiki/display/SITE/OSGi+Configuration+Admin+command+line+client.

You can find configuration files which loads and starts the Lightsabre bundles together with their dependencies in the folder Distribution/Configuration/target/. The configuration files are available for Equinox and Felix and for the ActiveMQ and the Stomp binding. For this demo we need the ActiveMQ version. The following instructions regard the usage of Equinox, an description for Felix can be found here.

Note: If you plan to use lightsabre for development from within Eclipse you can import the bundles listed in the configuration file as „Plug-ins and Fragments" and skip the following steps to set up two runtime environments.

Download a current version of Equinox from http://eclipse.org/equinox/ in this case 3.4.2 was used. After extracting the Equinox archive you will find a folder called plugins which contains the JAR file needed to start the framework. Create a new folder called runtime_publisher and copy the file org.eclipse.osgi_3.4.3.R34x_v20081215-1030.jar (version number might vary) from the plugin folder of the equinox distribution into it. In this folder create another folder called configuration, place the Equinox-ActiveMQ configuration file (equinox_activemq.config.ini.append) into it and rename it to config.ini. You should now have the following directory layout:

Now start the framework with the following command from within the runtime_publisher folder:

java -jar org.eclipse.osgi_3.4.3.R34x_v20081215-1030.jar -console

[Some log messages]

osgi>

If you type in the command "ss" on the OSGi prompt you will see a list of 12 bundles which should all be in the state "ACTIVE". You can now shout down the container by typing in "exit".

Now make a copy of the runtime_publisher and name it to runtime_consumer to have a separate runtime directory for each of the following demo parts.

Starting the Messaging System

This demo uses the Apache ActiveMQ 5.2 message broker which can be downloaded from the Apache ActiveMQ homepage (http://activemq.apache.org/download.html). After it has been downloaded and extracted it can be started from the command prompt by entering the following command in the ActiveMQ directory:

./bin/activemq

After the start up the message broker provides a simple web interface (http://0.0.0.0:8161/admin/) to monitor its basic functions.

4 The Demo App

4.1 Import Maven Projects

The project directory contains a Samples/SimpleDemo directory where the demo application is located. Both projects where build automatically so that the bundles are already available. But as we want to take a look at the source code of the bundles we are importing them into eclipse. To generate an Eclipse project for each component simply change to the directory of each component and type in:

mvm eclipse:eclipse

Afterwards you can import both projects into Eclipse.

4.3 Message Consumer

The Message consumer consists of two classes. The activator registers an EventHandler implementation and unregisters it when the bundle is stopped.

public void start(BundleContext context) throws Exception { 
    Dictionary props = new Hashtable(); 
    props.put(EventConstants.EVENT_TOPIC, "demo"); 
    reg = context.registerService(EventHandler.class.getName(),
                                  new DemoMessageReceiver(), props); 
}

The EventHandler implementation is done by the DemoMessageReceiver class which has one method which is called by the EventAdmin when an event is delivered. The implementation than simply prints the content of the message to std-out:

public class DemoMessageReceiver implements EventHandler { 
    public void handleEvent(Event event) {   
       System.out.println("DemoMessageReceiver: " + event.getProperty("message"));     
    }
}

4.3.1 Configuration

This bundle contains the necessary configuration for the EventDistributionSystem like the MessgaeProducer bundle:

com.fusesource.lightsabre.eds.name=DemoRecvForwaring 
com.fusesource.lightsabre.eds.direction=receive 
com.fusesource.lightsabre.eds.messaging.url=tcp://localhost:61616 
com.fusesource.lightsabre.eds.messaging.subject=DemoActivemqTopic 
com.fusesource.lightsabre.eds.messaging.binding=org.apache.activemq 
com.fusesource.lightsabre.eds.messaging.converter=jmsPlainTextMessageConverter

Further information on the configuration values can be found in the next section.

4.3.2 Running

To run the MessageConsumer start the OSGi container in the runtime_consumer folder as described at the beginning of this document. Afterwards you can install and start the MessageConsumer bundle which will trigger the configuration of the EDS (The path and version number may vary):

osgi> install file:///tmp/demo/trunk/Samples/SimpleDemo/MessageConsumer/target/MessageConsumer-0.5-SNAPSHOT.jar
Bundle id is 14

osgi> start 14

After the EDS is configured you can receive messages from the messaging topic. The next section will introduce the message publisher which publishes messages to this topic.

4.2 Message Publisher

The Message Publisher consists of only two classes. The bundle activator instantiates and displays the window and hides the window when the bundle is stopped. TheMessagePublisherWindow class creates the GUI components and uses a ServiceTracker to access the EventAdmin service:

 st = new ServiceTracker(bctx, EventAdmin.class.getName(), null) {

    @Override
    public Object addingService(ServiceReference reference) {
        eventAdmin = (EventAdmin) bctx.getService(reference);
        jbSend.setEnabled(true);
        return super.addingService(reference);
    }

    @Override
    public void remove(ServiceReference reference) {
        jbSend.setEnabled(false);
        eventAdmin = null;
        super.remove(reference);
    }
};
st.open();

It also defines an ActionListener implementation for the send button which creates a new event which contains the message and sends the event to the EventAdmin.

jbSend.addActionListener(new ActionListener() {
    public void actionPerformed(ActionEvent e) {
        /* Create and send an event containig the message */
        Dictionary<String, Object> props = new Hashtable<String, Object>();
        props.put("message", jtMessage.getText());
        Event ev = new Event("demo", props);
        eventAdmin.sendEvent(ev);
    }
});

As you can see, the code only uses the EventAdmin and has no special dependency to the EventDistributionSystem.

4.2.1 Configuration

The bundle also contains a properties file in the folder OSGI-INF/messaging/messaging.propertieswhich defines the appropriate configuration for the event distribution. This file is read by the BundleScanner which applies these properties to the ConfigurationAdmin. The EventDistributionSystem than obtains the configuration from the ConfigurationAdmin and creates a ForwardingContext which forwards all events from the event topic "demo" (Lines 7-8) to a messaging topic "DemoActivemqTopic" on an ActiveMQ messaging system(Lines 3-5).

(1)  com.fusesource.lightsabre.eds.name=DemoSendForwarding
(2)  com.fusesource.lightsabre.eds.direction=send
(3)  com.fusesource.lightsabre.eds.messaging.binding=org.apache.activemq
(4)  com.fusesource.lightsabre.eds.messaging.url=tcp://localhost:61616
(5)  com.fusesource.lightsabre.eds.messaging.subject=DemoActivemqTopic
(6)  com.fusesource.lightsabre.eds.messaging.converter=jmsPlainTextMessageConverter
(7)  com.fusesource.lightsabre.eds.event.topic=demo
(8)  com.fusesource.lightsabre.eds.event.filter=

4.2.2 Running

Start your OSGi container in the runtime_publisher folder as described at the beginning of this document. Afterwards you can install and start the MessageSender bundle with the following commands (The path and version number may vary):

osgi> install file:///tmp/demo/trunk/Samples/SimpleDemo/MessagePublisher/target/MessagePublisher-0.5-SNAPSHOT.jar
Bundle id is 14

osgi> start 14

When you start the bundle the following window will appear:

On the OSGi console you will see that the BundleScanner has found and applied the configuration from the configuration file. The EDS gets the configuration update and initializes the forwarding of the events:
Now you can send the first message via by hitting the send button in in the SendMessage window. The EDS will inform you that it forwards an event to the messaging system with some informational output on the console:
If you visit the ApacheMQ webinterface via http://0.0.0.0:8161/admin/ you can see the DemoActivemqTopic in the list with the messaging topics. You can also see how many messages have been forwarded to the topic:

The figure also shows that the topic has one consumer which is the MessageConsumer from the previous section. In the console window of the MessageConsumer the message that was just sent, appreared as it was received form the messaging topic: