Date: March 27, 2003
Java platform: Sun JDK 1.2 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.
Common Support Libraries | |||
Location |
Library | Available From | Notes |
add-ons/jmsmtp/lib/common | jdom.jar | jdom-b9-rc2.zip | |
add-ons/jmsmtp/lib/common | log4j-1.2.8.jar | jakarta-log4j-1.2.8.zip | Supports log4j-1.2.7 + |
|
|||
JBossMQ Support Libraries | |||
Location |
Library | Available From | Notes |
add-ons/jmsmtp/lib/common/jbossmq | jbossall-client.jar | http://www.jboss.org/ | Download JBoss server, files located in /client |
add-ons/jmsmtp/lib/common/jbossmq | jbossjmx-ant.jar | . | |
add-ons/jmsmtp/lib/common/jbossmq | xercesImpl.jar | Xerces-J-bin.2.4.0.zip | |
add-ons/jmsmtp/lib/common/jbossmq | xmlParserAPIs.jar | ||
SonicMQ Support Libraries | |||
Location |
Library | Available From | Notes |
add-ons/jmsmtp/lib/common/sonicmq | jmxri.jar | http://www.sonicmq.com/ | Download SonicMQ, files located in /lib |
add-ons/jmsmtp/lib/common/sonicmq | jndi.jar | ||
add-ons/jmsmtp/lib/common/sonicmq | mfcontext.jar | ||
add-ons/jmsmtp/lib/common/sonicmq | mgmt_agent.jar | ||
add-ons/jmsmtp/lib/common/sonicmq | mgmt_client.jar | ||
add-ons/jmsmtp/lib/common/sonicmq | mgmt_config.jar | ||
add-ons/jmsmtp/lib/common/sonicmq | sonic_Client.jar | ||
add-ons/jmsmtp/lib/common/sonicmq | sonic_mgmt_client.jar | ||
add-ons/jmsmtp/lib/common/sonicmq | sonic_mgmt.jar | ||
add-ons/jmsmtp/lib/common/sonicmq | xercesImpl.jar | Must be file from SonicMQ distribution | |
add-ons/jmsmtp/lib/common/sonicmq | xmlParserAPIs.jar | Must be file from SonicMQ distribution |
The current implementation ships with support for the following JMS Providers:
JMS Provider | Support Files |
JBossMQ | jmsmtp/lib/jbossmq |
SonicMQ | jmsmtp/lib/sonicmq |
When activated the JMS-MTP which uses the JBossMQ provider you will need to change the port JADE run on (1099) as this is also the same port number that is used by 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:
java
-classpath
./lib/jade.jar:./lib/jadeTools.jar:./add-ons/jmsmtp/lib:./add-ons/jmsmtp/lib/jmsmtp.jar.
jade.Boot
( for Unix ) java -classpath
.\lib\jade.jar;.\lib\jadeTools.jar;.\add-ons\jmsmtp\lib;.\add-ons\jmsmtp\lib\jmsmtp.jar.
jade.Boot
( for Windows )Once the MTP starts it loads the jars it needs from the following default locations:
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:hostname:port/queuename)
To activate the JMS-MTP to connect to the 'jade/frodo' queue on a JBossMQ 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:jbossmq:xml:non_persistent:::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
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.
Addresses used with the JMS-MTP are in the following format:
jms:provider_type:messge_type:persistence:username:password:hostname:port/queuename
jms:sonicmq:xml:persistent:edcurry:edspass:message.broker.foobar.com:1099/jade/jade-platform.foobar.com:1098
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 (TODO).
jms-mtp.properties### JMS-MTP
Configuration
#############################################
ie.nuigalway.ecrg.jade.jmsmtp.fipaxmlutil.parser=org.apache.xerces.parsers.SAXParser
### Default Address
Settings
############################
ie.nuigalway.ecrg.jade.jmsmtp.default.providerType=jbossmq
ie.nuigalway.ecrg.jade.jmsmtp.default.brokerURL=127.0.0.1:1099
ie.nuigalway.ecrg.jade.jmsmtp.default.queueName=/jade/127.0.0.1
## 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
#############################################
###
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
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;
public abstract Queue getOrCreateQueue(JMSAddress jmsTA) throws
Exception;
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:
JADE is a
trademark of CSELT.
SonicMQ is a trademark
of Sonic Software.
JBoss and
JBoss Group are a registered trademark and servicemark of Marc Fleury under
operation by The JBoss Group, LLC.
JADE has been developed jointly by CSELT and the Computer Engineering Group of the University of Parma.
The JMS-MTP was developed in the Enterprise Computing Research Group
(ECRG) at the National University of
Ireland, Galway by Edward
Curry.
The support of the Informatics Research Initiative of Enterprise Ireland is gratefully
acknowledged.
Copyright 2002 Enterprise Computing Research Group.