OpenJmsAdapter

Introduction

This is the website for OpenJmsAdapter - a small, lightweight JMS framework - that will take away all the low level work from you and let you conentrate on just sending the message.

OpenJmsAdapter is developed and released under the LGPL license.

Current state of development

OpenJmsAdapter is curently being developed and in the beta stage. You can download the 0.1 version of the framework from here. This version has the following features

The adapter can send BytesMessage, TextMessage and ObjectMessage types to ActiveMQ and OpenMQ servers using the built in client code.
You need to configure the adapter using a Yaml file or a database configuration. The database configuration is loaded using Hiberate.
The configuration requires - the server url, username and password, the destination name, the type of destination - queue or topic, the operation - publish or receive, the last sequence sent on this destination, the last sequence received on this destination.
Once the adapter is configured using these parameters, you can include the jar in your application, instantiate the client using the appropriate configuration file and send a message.
You can write your own clients - using the database or Yaml configuration - for any JMS server without much effort.
Each message is stamped with a sequence number in the header property field "OpenJMSAdapterSequence" - this is a long property
The message is also stamped with the name of the topic or queue where it originated. This is stored in the String property "DestinationName"

You can browse the code for the adapter here - http://openjmsadapter.svn.sourceforge.net/

I am developing this adapter in my free time, and am still coming up with a road map of the features that I would be puting in the future versions. You can send in your feedback and suggestions to openjmsadapter@gmail.com .It will be much appreciated.

The adapter took about 5 days of work to build in the current state. Thats about 40 hours of work. If you feel that we saved you that much effort and would not mind donating some money to the project so that those who worked on it can spend more time on this, please visit

Publishing a message using a Yaml Configuration

Lets say you want to publish a message to an ActiveMQ client using Yaml configuration.

Create a configuration file, config.yml, and put this in the file.



--- 

JMSConnectionPassword: manager

JMSConnectionUrl: "tcp://localhost:61613"

JMSConnectionUser: system

destinations: - destinantionName: test.queue

destinationType: queue

lastSequenceReceived: -1

lastSequenceSent: -1

operationType: publish

What you are telling the adapter here is that there is a local server at 61613, its credentials and you are configurating a destination. This destination is "test.queue", its a queue and you will publish to this queue. The last sent sequence is -1 meaning the sequence will start from 0, and the received sequence is ignored here. After you connect to the server using OpenJmsAdapter and publish the messages and disconnect, the adapter will update this Yaml file and set the last sent sequence to the last value it pubslished before disconnect. If you were receiving the message then it would set the last sequence received before the disconnect.

Now, we need to write some code to send the message.

Make sure the openjmsadapter.jar file and all the other libraries in the distribution - you can ignore the hibernate and mysql jar files - are in your class path.

This is how you publish a BytesMessage.



ActiveMQClient client = new ActiveMQClient("config.yml");

client.connect();        

long sentSeq = client.publishToQueueAsBytes("HELLO", "test.queue");

client.disconenct();

Thats it.

And this is how you receive a message. You need to create a config_1.yaml for receiving a message.



ActiveMQClient client1 = new ActiveMQClient("config_1.yml");

client1.connect();

String text = client1.receiveBytesMessageFromQueueIntoString("test.queue");

client1.disconenct();

The client you used here is in the package com.openjmsadapter.client.yaml

There are options to publish and receive a TextMessage and an ObjectMessage.

Publishing a message using a database configuration

If you want to publish a message using the database configuration, its similar. But will need some database setup.

Find a database, and create these tables. The below scripts are for MySQL.



DROP TABLE IF EXISTS `openjmsadapter`.`jms_connection_parameters`;

CREATE TABLE  `openjmsadapter`.`jms_connection_parameters` (`id` bigint(20) NOT NULL,

`url` varchar(255) DEFAULT NULL,

`username` varchar(255) DEFAULT NULL,

`password` varchar(255) DEFAULT NULL,

PRIMARY KEY (`id`)
) 





DROP TABLE IF EXISTS `openjmsadapter`.`jms_destination_parameters`;

CREATE TABLE  `openjmsadapter`.`jms_destination_parameters` (`id` bigint(20) NOT NULL,

`destinationName` varchar(255) DEFAULT NULL,

`destinationType` varchar(255) DEFAULT NULL,

`operationType` varchar(255) DEFAULT NULL,

`lastSequenceSent` bigint(20) DEFAULT NULL,

`lastSequenceReceived` bigint(20) DEFAULT NULL,

PRIMARY KEY (`id`)
)

Put the connection details in the connection parameters table. Right now you can put only one server there.
Put the destinations in the destination parameters table.

Then create a hibernate configuration using the below template.





<?xml version="1.0" encoding="UTF-8"?><br />
<!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD 3.0//EN" "<span class="url-link"><a href="http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd</a></span>"><br />
<hibernate-configuration><ul><session-factory><ul><property name="hibernate.dialect">org.hibernate.dialect.MySQLDialect</property><br />
<property name="hibernate.connection.driver_class">com.mysql.jdbc.Driver</property><br />
<property name="hibernate.connection.url">jdbc:mysql://localhost:3306/openjmsadapter</property><br />
<property name="hibernate.connection.username">root</property><br />
<property name="hibernate.connection.password">admin</property><br />
<property name="hibernate.connection.pool_size">1</property><br />
<property name="hibernate.show_sql">true</property><br />
<property name="hibernate.connection.autocommit">true</property><br />
<property name="hibernate.hbm2ddl.auto">update</property><br />
<property name="hibernate.current_session_context_class">thread</property><br />
<mapping class="com.openjmsadapter.configuration.database.JmsConnectionParameters" package="com.openjmsadapter.configuration.database" resource="com/openjmsadapter/configuration/database/JmsConnectionParameters.hbm.xml"/><br />
<mapping class="com.openjmsadapter.configuration.database.JmsDestinationParameters.hbm" package="com.openjmsadapter.configuration.database" resource="com/openjmsadapter/configuration/database/JmsDestinationParameters.hbm.xml"/></ul>
</session-factory></ul>
</hibernate-configuration>

After that, it is pretty much similar to what you saw above for Yaml, except that the classes are now in the package com.openjmsadapter.client.database

This is how you publish a BytesMessage.



ActiveMQClient client = new ActiveMQClient("config.yml");

client.connect();        

long sentSeq = client.publishToQueueAsBytes("HELLO", "test.queue");

client.disconenct();

Thats it.

And this is how you receive a message. You need to create a config_1.yaml for receiving a message.



ActiveMQClient client1 = new ActiveMQClient("config_1.yml");

client1.connect();

String text = client1.receiveBytesMessageFromQueueIntoString("test.queue");

client1.disconenct();

There are options to publish and receive a TextMessage and an ObjectMessage.

Creating a custom Yaml configuration client

Lets say you want to publish messages to a XyzMQ server. Then you can create your own client class by simply doing this.





public class XyzMQClient extends YamlConfigClient{

private static Logger logger = Logger.getLogger("OpenJMSAdapter");

private XyzMQConnectionFactoryBuilder connectionFactoryBuilder;



public XyzMQClient(String configFileName) throws FileNotFoundException {super(configFileName);
}



public void disconnect() throws OpenJMSAdapterException {disconnectJMSConnection();
}



public void reconnectWith(long timeout) throws OpenJMSAdapterException {delayedReconnect(timeout);
}



public void connect() throws OpenJMSAdapterException {logger.info("Creating connection factory");

connectionFactoryBuilder = new XyzMQConnectionFactoryBuilder();

logger.info("Completed creating connection factory.");

connectUsingFactoryWithUsernamePassword(connectionFactoryBuilder.getConnectionFactory(getConfig()));

//or simply 

//connectUsingFactory(connectionFactoryBuilder.getConnectionFactory(getConfig()));
}

The Connection Factory builder is written as follows





public class XyzMQConnectionFactoryBuilder {

private static Logger logger = Logger.getLogger("OpenJMSAdapter");

private ConnectionFactory connectionFactory;



public XyzMQConnectionFactoryBuilder() {//do nothing
}



public ConnectionFactory getConnectionFactory(AdapterConfiguration config) throws OpenJMSAdapterException {try{

if (connectionFactory == null) {logger.debug("Creating XyzMQ conenction factory with Yaml configuration");

XyzMQConnectionFactory factory=new XyzMQConnectionFactory();

...

//the code to set any other properties etc

...

connectionFactory =factory;

logger.debug("Completed creating XyzMQ conenction factory with Yaml configuration");

return connectionFactory;
} else {logger.debug("Returning already existing XyzMQ conenction factory");

return connectionFactory;
}

}catch(JMSException jmse){throw new OpenJMSAdapterException("Error creating OpenMQConnectionFactory", jmse);
}
}
}

The AdapterConfiguration class gives you access to all the properties that you configure on the adapter.

Creating a custom database configuration client

For a database configuration client, everything remains the same. Just replace YamlConfigClient with DatabaseConfigClient.