RabbitOSGi - Utilities for RabbitMQ in OSGi
===========================================

This project has been created to explore ways of using the RabbitMQ messaging broker from OSGi, in particular how we can 
integrate with the Service Registry to get ESB-like functionality.

Running Equinox
---------------

To launch Equinox, type the following command:

    java -jar runtime/equinox.jar -console

We are using the FileInstall bundle from Peter Kriens (http://www.aqute.biz/Code/FileInstall). Any valid bundles copied 
into the `load` directory will be automatically installed and started. It should not be necessary to restart Equinox 
during development and testing.


Building Bundles
----------------

To build all bundles, simply run ant. Bundles are generated in the `load` directory so that they are automatically 
installed in the running Equinox instance.

To build an individual bundle, the Bnd tool (also by Peter Kriens, http://www.aqute.biz/Code/Bnd) can be used as 
follows:

    bnd build -eclipse .. commands.bnd

This style of the command uses the presence of an Eclipse project in the parent directory in order to calculate a 
classpath. You can also use an explicit classpath as follows:

    bnd build -classpath ../classes commands.bnd

Note that "bnd" is assumed to be an alias for `java -jar bnd.jar`.

If you are developing in Eclipse and have Bnd installed as an Eclipse plug-in, individual bundles can be built simply by 
right-clicking on the .bnd file and selecting Make Bundle. See the Bnd documentation for instructions on installing as 
an Eclipse plug-in.

Connections Bundle
------------------

The "connections" bundle registers a ManagedServiceFactory (MSF) as defined by the OSGi Configuration Admin 
specification. This allows us to create connections declaratively using Configuration records. We can use this MSF in 
conjunction with the FileInstall bundle, which creates Configuration records based on properties files it finds in the 
`load` directory.

To connect to a RabbitMQ broker on localhost with the default username, password and virtual host, create a file in the 
load directory named rabbitmq.connections-localhost.cfg with the following content:

    name=mycon
    host=localhost
    username=guest
    password=guest
    vhost=/

Additional connections can be created in the same way by using a different suffix after the hyphen in the filename.

Exchanges Bundle
----------------

This bundle adds a declarative way to create AMQP exchanges for a particular connection, using Config Admin. To declare 
an exchange named FooEx on the `local` connection, create a file named `rabbitmq.exchanges-fooex.cfg` in the load 
directory with the following content:

    connection.name=local
    exchange.name=FooEx
    exchange.type=direct        #optional, defaults to "direct"
    exchange.passive=false      #optional, defaults to false
    exchange.durable=false      #optional, defaults to false
    exchange.autoDelete=false   #optional, defaults to false

This will cause a service of type Exchange to be registered in the Service Registry. Exchange is an interface that 
simply offers the `basicPublish` method. This allows clients that want to simply send a message in "fire and forget" 
mode to quickly obtain a pre-declared exchange and publish to it without going through the hassle of opening a 
connection and creating a channel.

Consumer Bundle
---------------

This bundle watches for connection instances published in the Service Registry and creates a simple consumer for each 
one. The consumer receives messages from the "FooQueue" queue and simply prints them to the console.

TODO: explore how to make this more declarative and POJO-based. 

Commands Bundle
---------------

This bundle provides commands into the OSGi console for manual control over the RabbitMQ broker. Note that it runs only 
under Equinox, since extending the console uses a framework-specific API (the other bundles will work under any OSGi R4 
framework).

The commands provided are as follows:

  * listConns: List connected channels.
  * declExchange: Declare an exchange on the specified broker connection.
  * declQ: Declare a queue.
  * bindQ: Bind a queue to an exchange.
  * publish: Publish a message to an exchange.
  * receive: Retrieve a single message from a queue and print it.

Example Usage
-------------

After building the bundles, the following sequence of commands can be used to test sending and receiving messages:

    osgi> listConns
    {mycon}={connection.host=localhost}
        Registered by bundle: channel 0
    
    osgi> declExchange mycon FooEx direct
    Exchange Declared
    
    osgi> declQ mycon FooQueue
    Queue Declared
    
    osgi> bindQ mycon FooQueue FooEx FooQueue
    Queue Bound
    
    osgi> publish mycon FooEx FooQueue "Hello World"
    Message Published
    
    osgi> ---Message Received---
    Hello World


Notes on "OSGifying" the RabbitMQ Client Library
------------------------------------------------

In order to use the RabbitMQ client library under OSGi it must be transformed into an OSGi bundle. This process 
(sometimes called "bundleizing" or "OSGifying") involves introspecting the bytecode contained in the library and 
generating the necessary dependency declarations to be placed in the MANIFEST.MF. It must also be done for the Apache 
Commons IO library on which RabbitMQ depends.

Bnd is able to OSGify libraries but it must be provided certain information such as the name and version of the new 
bundle. This information is provided by two files in the `original` subdirectory: com.rabbitmq.client_1.5.0.beta.bnd and 
org.apache.commons.io_1.2.0.bnd. To generate the bundles we can simply run Bnd as follows:

    bnd com.rabbitmq.client_1.5.0.beta.bnd
    bnd org.apache.commons.io_1.2.0.bnd

The resulting bundle JARs can still be used as ordinary JAR files in traditional non-OSGi Java environments. It would be 
advantageous therefore to incorporate this step into the main build for the RabbitMQ client library.

Licence
-------

Copyright (c) 2009 Neil Bartlett.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse 
Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html