How to use the Java Message Service (JMS) MTP with JADE

Date: January 14, 2004

JMS-MTP version 1.0

Java platform: Sun JDK 1.4 Linux

JADE version 2.1

Since JADE 2.1, FIPA-compliant Message Transport Protocols (MTP) can be plugged and activated at run-time on any JADE container. By default, a JADE platform uses a Sun ORB implementation of an MTP . However, as an alternative, a Java Messaging Service (JMS) implementation is also available. This tutorial describes how to install and use this JMS implementation in JADE. Please note this MTP only works on JDK 1.4. For further information on the JMS-MTP see the Agent Interaction Tutorial

Installation

• The JMS-MTP must be downloaded from the JADE add-ons download page.
• The latest version 1.0 can also be downloaded from http://ecrg.it.nuigalway.ie/downloads/jmsmtp1.0.zip
• The older version 0.5 is available from http://ecrg.it.nuigalway.ie/downloads/jmsmtp-0.5.zip
• After downloading, extract the JMS-MTP package under the root of your jade installation. You should have a hierarchy like jade/add-ons/jmsmtp
• The following table shows the required files needed to run the JMS-MTP. The common support files are mandatory, they must be downloaded.
• You must also download the support libraries for the JMS provider(s) you want to run and place them in the specified directory. (Note these directory locations may be changed via the jms-mtp.properties file)

Compiling

• ant compile - compiles the JMS-MTP classes
• ant lib - creates the jmsmtp.jar archive
• ant clean - removes the compiled classes and the .jar archive
• ant doc - creates javadoc for the JMS-MTP
• execute_jmsmtp - run a JADE platform with the JMS-MTP activated
• exec_example_client - runs the example Java client
• exec_example_container - runs the example container with the JMS-MTP activated

Usage

The current implementation ships with support for the following JMS Providers:

When activated the JMS-MTP which uses the OpenJMS/JBossMQ providers you will need to change the port JADE run on (1099) as this is also the same port number that is used by OpenJMS/JBoss's JNDI service. To specify a port for JADE to run on simple use the -port switch on startup.

In order to use the JMS-MTP, the jmsmtp.jar and jms-mtp.properties file must be on the classpath when starting( either by including it into the $CLASSPATH environment variable - %CLASSPATH% under windows or by specifying it on the command line ).

Here is an example of how you would start the platform assuming you are in the root of the Jade directory:

Once the MTP starts it loads the jars it needs from the following default locations:

• Common JMS-MTP Library: /usr/local/jade/add-ons/jmsmtp/lib/common
• OpenJMS JMS Provider Library: /usr/local/jade/add-ons/jmsmtp/lib/openjms
• JBossMQ JMS Provider Library: /usr/local/jade/add-ons/jmsmtp/lib/jbossmq
• SonicMQ JMS Provider Library: /usr/local/jade/add-ons/jmsmtp/lib/sonicmq

The location of each of these libraries can be changed via the jms-mtp.properties file (covered later in the tutorial).

It is possible to activate one ore more communication endpoints. There are two main ways for doing such an activation:

Activating a JMS-MTP from the command line

When you start a JADE container it is possible to configure a MTP from the command line. Using the -mtp command line option, a transport endpoint lives as long as its container is up; when a container is shut down, the JMS-MTP will be deactivated and the AMS information is updated accordingly. To start a JMS-MTP on JADE startup, the following parameter must be specified on the command line.

-mtp ie.nuigalway.ecrg.jade.jmsmtp.MtpBoot(jms:provider_type|message_type|persistence:username|password|protocol://hostname:port/queuename)

To activate the JMS-MTP to connect to the 'jade/frodo' queue on a OpenJMS broker on msgserver.foobar.com:1099 using no username or password with xml, non persistent messages you would use the following line (For more information on JMS-MTP Address Structure see the next section):

-mtp ie.nuigalway.ecrg.jade.jmsmtp.MtpBoot(jms:openjms|xml|non_persistent|||rmi://msgserver.foobar.com:1099/jade/frodo)

Activating a JMS-MTP from the graphical management console

The JADE RMA console enables a more flexible management of the MTPs, allowing to activate and deactivate transport protocols during normal platform operations.

Select a container from the GUI, click the right button of the mouse and a popup menu appears. Choose the Install a new MTP option and a dialog will be shown. Here the following information can be set: the container to install the new MTP on (if different from the selected one), the fully qualified name of the class implementing the jade.mtp.MTP interface, and (if it is supported by the chosen protocol) the transport address that will be used to contact the new MTP.

In order to install a new JMS-MTP one should input the following information

• ie.nuigalway.ecrg.jade.jmsmtp.MtpBoot as the class name
• optionally the transport address that will be used by the new MTP.

Choosing Uninstall an MTP shows a dialog where the user can select from a list one of the currently installed MTPs and remove it from the platform.

Configuration

JMS-MTP Address Structure

Addresses used with the JMS-MTP are in the following format:

jms:provider_type|messge_type|persistence|username|password|protocol://hostname:port/queuename

• MTP Protocol : Mandatory prefix to identify protocol -- 'jms:'
• Provider Type : JMS provider used by this address, MTP currently supports OpenJMS, JBossMQ and SonicMQ-- ( 'openjms' | 'jbossmq' | 'sonicmq' )
• Message Type : Message Type used at by this address -- ( 'xml | 'map' )'
• Message Persistence : Persistence setting for the Address -- ( 'persistent' | 'non_persistent' )
• Username : Optional username for this address (Security implemented by JMS provider)
• Password : Optional password for this address (Security implemented by JMS provider)
• JMS Protocol : Protocol used to connect to the JMS provider -- 'rml://'
• Broker URL : URL of the message broker servicing this address -- 'message.broker.foobar.com:1099'
• Queue Name : Name of the queue on the broker for this address -- 'jade/jade-platform.foobar.com:1098'

• Provider Type : SonicMQ -- 'sonicmq'
• Message Type : FIPA XML -- 'xml
• Message Persistence : Persistent -- 'persistent'
• Username : -- 'edcurry'
• Password : -- 'edspass'
• JMS Protocol : -- 'tcp://'
• Broker URL : -- 'message.broker.foobar.com:1099'
• Queue Name : -- 'jade/jade-platform.foobar.com:1098'

jms:sonicmq|xml|persistent|edcurry|edspass|tcp://message.broker.foobar.com:1099/jade/jade-platform.foobar.com:1098

Message Settings

• FIPA XML -- 'xml'
  Messages encoded as XML are converted into the FIPA Agent Message Transport Envelope Representation in XML Specification. Messages are encoded and decoded using Xerces as the default parser (the parser used can be altered in the configuration file).
• JMS-MTP MapMessage -- 'map'
  The overhead of parsing XML may elongate the time required for the consumer to process the message, thereby limiting the overall message throughput of the application. In many cases, the MapMessage has all the same virtues as XML without the performance hit of text parsing. With respect to portability, most JMS vendors will automatically convert a MapMessage produced by a Java application to a non-Java environment, hence the MapMessage is an alternative to using the FIPA XML format.
  
  However currently there is no FIPA specification for a MapMessage format, thus usage of this format is limited to scenarios where both sides of the communication are taking place using the JMS-MTP. It is our hope that FIPA will address this issue by defining a standard specification for a MapMessage.

• Persistent -- 'persistent'
  When messages are marked as persistent, it is the responsibility of the JMS provider to guarantee that the message will never be lost. In order to fulfill this responsibility the JMS provider must store the message in a non-volatile medium such as a hard disk.
• Non Persistent -- 'non_persistent'
  With Non-persistence messages the server does not have this responsibility and therefore doesn't need to persist the messages to disk, hence non-persistent messages generally require less resources and can be delivered in less time than persistent ones. Higher levels of message throughput can also be achieved by using non-persistent messages at the expense of reliability.

Configuration File

The JMS-MTP is configurable by altering its jms-mtp.properties file. Aspects of the JMS-MTP configurable from this file include the xml parser used, default address settings and any jms provider specific configurations. For the SonicMQ provider broker administration details and queue properties are configurable. For more information on these settings please see the JMS-MTP SonicMQ Provider tutorial.

### JMS-MTP Configuration
#############################################
## The JMS-MTP needs a SAX XML Parser. The parser used can be by specifying one on the classpath
## J2SE v1.4 default parser is used as default, this option is mandatory with JDK 1.3 or earlier
ie.nuigalway.ecrg.jade.jmsmtp.fipaxmlutil.parser=org.apache.crimson.parser.XMLReaderImpl

### Default Address Settings
############################
ie.nuigalway.ecrg.jade.jmsmtp.default.providerType=openjms
ie.nuigalway.ecrg.jade.jmsmtp.default.brokerURL=rmi://127.0.0.1:1099
ie.nuigalway.ecrg.jade.jmsmtp.default.queueName=/jade/localhost

## Location of JMS-MTP Library
ie.nuigalway.ecrg.jade.jmsmtp.lib=/usr/local/jade/add-ons/jmsmtp/lib

### Optional: Username and password for queue
ie.nuigalway.ecrg.jade.jmsmtp.default.username=
ie.nuigalway.ecrg.jade.jmsmtp.default.password=

### Message Persistence options: persistent | non_persistent
ie.nuigalway.ecrg.jade.jmsmtp.default.messagePersistence=persistent

### Message Type options: xml | hashmap
ie.nuigalway.ecrg.jade.jmsmtp.default.messageType=xml

### JMS Provider Settings
#############################################

### OpenJms
############
ie.nuigalway.ecrg.jade.jmsmtp.providerType.openjms.providerAdmin.className=ie.nuigalway.ecrg.jade.jmsmtp.OpenJmsProviderAdmin
ie.nuigalway.ecrg.jade.jmsmtp.providerType.openjms.lib=/usr/local/jade/add-ons/jmsmtp/lib/openjms

### JBossMQ
############
ie.nuigalway.ecrg.jade.jmsmtp.providerType.jbossmq.providerAdmin.className=ie.nuigalway.ecrg.jade.jmsmtp.JBossMqProviderAdmin
ie.nuigalway.ecrg.jade.jmsmtp.providerType.jbossmq.lib=/usr/local/jade/add-ons/jmsmtp/lib/jbossmq

### SonicMQ
############
ie.nuigalway.ecrg.jade.jmsmtp.providerType.sonicmq.providerAdmin.className=ie.nuigalway.ecrg.jade.jmsmtp.SonicMqProviderAdmin
ie.nuigalway.ecrg.jade.jmsmtp.providerType.sonicmq.lib=/usr/local/jade/add-ons/jmsmtp/lib/sonicmq

### SonicMQ Broker Domain settings
ie.nuigalway.ecrg.jade.jmsmtp.providerType.sonicmq.domain.name=Domain1
ie.nuigalway.ecrg.jade.jmsmtp.providerType.sonicmq.domain.username=Administrator
ie.nuigalway.ecrg.jade.jmsmtp.providerType.sonicmq.domain.password=Administrator
ie.nuigalway.ecrg.jade.jmsmtp.providerType.sonicmq.domain.brokerViewName=Brokers/Broker1

### SonicMQ default queue settings
ie.nuigalway.ecrg.jade.jmsmtp.providerType.sonicmq.queue.maxSize=50000
ie.nuigalway.ecrg.jade.jmsmtp.providerType.sonicmq.Queue.saveThreshold=25000

Adding Support for Additional JMS Providers

JMS is based on the concept of universal interfaces to proprietary vendor specific Messaging Systems. Numerous vendors currently ship JMS compatible MOM products, these include IBM MQSeries, Sun JMQ, Sonic Software's SonicMQ and JBoss Group's JBossMQ.

The JMS specification provides a consistent API set that gives access to the common features of messaging system, however it does not define aspect of the administration of a messaging service. Hence the administration of the service is still vendor specific, for example, the dynamic creation of a queue at runtime is still provider specific. Since the JMS MTP relies on the ability of a platform to create a new queue on a provider at runtime, we have exposed an interface to allow new JMS providers, with their vendor specific code, to be easily 'plugable' into the JMS MTP.

To add support for an additional JMS provider you will need to implement the ProviderAdmin interface in the ie.nuigalway.ecrg.jade.jmsmtp.common package. This interface has the following two methods:

• public abstract QueueConnectionFactory getQueueConnectionFactory(JMSAddress jmsTA) throws Exception;
  -- Method used to get get a queue connection factory on the JMS provider
  
• public abstract Queue getOrCreateQueue(JMSAddress jmsTA) throws Exception;
  -- Method used to get or create the queue contained in the transport address on the JMS provider
  

Once this interface has been implemented you will need to include it in the JMS-MTP configuration file. The following property will need to be set in the jms-mtp.properties file.

ie.nuigalway.ecrg.jade.jmsmtp.providerType.XXX.providerAdmin.className=YYY

Where XXX is the name by which your provider will be identified in JMS Addresses. ie. SonicMQ is known as 'sonicmq'.
Where YYY is the fully qualified classname of your implementation of the ProviderAdmin interface

It is also possible for JMS Providers to be configured from the jms-mtp.properties file by using the following method:

JmsMtpConfig.getProperty(String propName, String defaultValue)

For example the SonicMQ provider allow for the Maximum Queue size to be set in the configuration file with the following key:

ie.nuigalway.ecrg.jade.jmsmtp.providerType.sonicmq.queue.maxSize=50000

The directory containing support files (jars) for the provider must be specified in the configuration file under the following key:

ie.nuigalway.ecrg.jade.jmsmtp.providerType.XXX.lib=YYY

Where XXX is the name by which your provider will be identified in JMS Addresses. ie. SonicMQ is known as 'sonicmq'.
Where YYY is the directory containing the jms providers jars, for example the following configuration locates the support files for the SonicMQ JMS provider in the '/usr/local/jade/add-ons/jmsmtp/lib/sonicmq' directory..

ie.nuigalway.ecrg.jade.jmsmtp.providerType.sonicmq.lib=/usr/local/jade/add-ons/jmsmtp/lib/sonicmq



The JMS MTP currently ships with support for the following JMS providers:

• OpenJMS
• JBossMQ
• SonicMQ