Prerequisites for running this sample:

Geronimo 1.0
Websphere MQ 6.0
OpenJMS 0.7.7

...

Integrating Third Party JMS Provider with Geronimo

ActiveMQ message broker can be embedded in another product and Geronimo uses this feature to bundle ActiveMQ. Geronimo uses GBean architecture to manage the lifecycle of ActiveMQ. The properties of ActiveMQ are exposed as GBean properties and the life cycle methods start and stop are managed by the kernel.
Image Removed
Back to Top

ActiveMQ is accessed in Geronimo by means of a JCA 1.5 Resource Adapter (RA). Resource Adapter provides connection, transaction, security and work management. By means of Outbound connections of ActiveMQ RA J2EE components in Geronimo can send messages to Queue or Topic in ActiveMQ. Inbound connections of Resource Adapter provide activation of Message Beans.
Image Removed
Back to Top

Integrating JMS Provider with Geronimo

Any third party JMS provider can be integrated with Geronimo by means of a JCA 1.5 ResourceAadapter for JMS. The JMS RA wraps JMS API for creating connections to Queues or Topics and also provides Inbound Communication from a Queue or Topic.
Image Removed
The properties for the Resource Adapter are configured in the ra.xml. These properties are:

Outbound properties - Used to create outbound queue and topic connections

• url - JNDI provider url (for example ldap://test/o=test,c=com, file: /C:/JNDI-Directory).
• icf - Initial Context Factory (for example com.sun.jndi.fscontext.RefFSContextFactory).
• name - Factory Name (for example ivtQCF).

Inbound properties - Used to create inbound connections to MDB

• url - JNDI provider url.
• icf - Initial Context Factory.
• name - Factory Name.
• destination - Destination to pick messages form (for example Queue Name).

Administered Objects - Used to define Queue and Topic Objects

• Physical Name - name of queue or topic created in JNDI of Geronimo

The properties of RA are mapped to Geronimo specific RA plan (geronimo-mq.xml) which contains instance specific properties for outbound connections and administered objects.

Any third party JMS provider can be integrated with Geronimo by means of a JCA 1.5 resource adapter for JMS. The JMS RA wraps JMS API for creating connections to Queue's or Topic's and also provides Inbound Communication from a Queue or Topic.

Image Added

The properties for the Resource Adapter are configured in the ra.xml. These properties are:

Outbound properties - Used to create outbound queue and topic connections

• url - JNDI provider url (for example ldap://test/o=test,c=com, file: /C:/JNDI-Directory).
• icf - Initial Context Factory (for example com.sun.jndi.fscontext.RefFSContextFactory).
• name - Factory Name (for example gerQCF).

Inbound properties - Used to create inbound connections to MDB

• url - JNDI provider url.
• icf - Initial Context Factory.
• name - Factory Name.
• destination - Destination to pick messages form (for example queue name ivtQ).

Administered Objects - Used to define Queue and Topic Objects

• Physical Name - name of queue or topic created in JNDI of Geronimo

The geronimo-ra.xml contains Apache Geronimo specific properties for resource adapter. The following example shows an excerpt from the geronimo-ra.xml.

<outbound-resourceadapter>
...
 <connection-definition>
   <connectiondefinition-instance>
     <name>JMSQueueFactory</name>
	<config-property-setting name="url"></config-property-setting>
	<config-property-setting name="icf"></config-property-setting>
	<config-property-setting name="name"></config-property-setting>
	<connectionmanager>
...
</connection-definition>
<adminobject>
...
<adminobject-instance>
     <message-destination-name>ivtQ</message-destination-name>
     <config-property-setting name="PhysicalName">queue1</config-property-setting>
</

<outbound-resourceadapter>
...
 <connection-definition>
   <connectiondefinition-instance>
     <name>JMSQueueFactory</name>
        <config-property-setting name="url"></config-property-setting>
        <config-property-setting name="icf"></config-property-setting>
        <config-property-setting name="name"></config-property-setting>
        <connectionmanager>
...
</connection-definition>
<adminobject>
...
<adminobject-instance>
     <message-destination-name>ivtQ</message-destination-name>
     <config-property-setting name="PhysicalName">queue1</config-property-setting>
</adminobject-instance>
</adminobject>
 <adminobject>
    <adminobject-instance>
       <message-destination-name>ivtT</message-destination-name>
        <config-property-setting name="PhysicalName">topic1</config-property-setting>
 </adminobject-instance>
</adminobject>
...

geronimo-ra.xml can be used to configure instances of resource adapters for different JMS providers. The example covered in at the end of this article shows has two such configurations , one for OpenJMS and one for WebsphereMQ. The connection definition properties are changed for different JMS providers. The outbound communication of Resource Adapter uses these properties to get a connection factory and create connections to Queue or Topic.

Back to Top

Deploying JMS Resource Adapter

This section shows how to deploy a JMS Resource Adapter and configure a J2EE application to use OpenJMS and WebSphereMQ as JMS providers. RA can be deployed in the server scope and instances can be used within scope of application.

The following steps show how to deploy the JMS Resource Adapter and configure OpenJMS and WebSphereMQ providers for Geronimo.

Back to Top

Configuring OpenJMS

OpenJMS starts RMI naming server on port 1019. This will conflict with the default RMI naming port in Geronimo. You will have to change the configuration for OpenJMS to use a different port and then start the OpenJMS server. Create QueueConnectionFactory and TopicConnectionFactory objects for OpenJMS. Define Queue's and Topics in openjms.xml. The following example shows relevant sections of the configuration file.

...
<Connector scheme="rmi">
      <ConnectionFactories>
        <QueueConnectionFactory name="JmsQueueConnectionFactory" />
        <TopicConnectionFactory name="JmsTopicConnectionFactory" />
        <QueueConnectionFactory name="openJMSQCF" />
        <QueueConnectionFactory name="openJMSTCF" />
      </ConnectionFactories>
    </Connector>
...
<RmiConfiguration embeddedRegistry="true"
                      registryHost="localhost"
                      registryPort="1030"/>
...
<AdministeredDestinations>
    <AdministeredTopic name="topic1">
      <Subscriber name="sub1" />
      <Subscriber name="sub2" />
    </AdministeredTopic>

    <AdministeredQueue name="queue1" />
    <AdministeredQueue name="queue2" />
    <AdministeredQueue name="queue3" />
  </AdministeredDestinations>

Deploy a JMS Resource Adapter with server scope.
java -jar <geronimo_home>\bin\deployer.jar gerjms<sample_home>\externaljms-1.0.rar

Deploy an enterprise application that uses OpenJMS.
java -jar <geronimo_home>\bin\deployer.jar gerjms.ear <plan_home>\.jar <sample_home>\externaljms.ear <sample_home>\geronimo-application-openjms.xml

The following example shows sections of Geronimo application plan for using OpenJMS. The properties for Outbound and Inbound communication are specified in the Message Bean and the Connector.

<application xmlns="http://geronimo.apache.org/xml/ns/j2ee/application" 
configId="jms.ear"  parentIdparented="jms.rar">

<module>
    <web>GERJMSWAR.war</web>
    ...
</web-app>
</module>
<module>
     <ejb>GERJMSEJB.jar</ejb>
     ...
      <message-driven>
      <ejb-name>JMSMDB</ejb-name>
      <resource-adapter>
        	<resource-link>JMSRA_1</resource-link>
      </resource-adapter>
     <activation-config>
        	<activation-config-property>
        	<activation-config-property-name>url</activation-config-property-name>
        	<activation-config-property-value>
		                  tcp://localhost:3035
         		</activation-config-property-value>
        	</activation-config-property>
        property>
	<activation-config-property>
        	<activation-config-property-name>icf</activation-config-property-name>
        	<activation-config-property-value>
		                  org.exolab.jms.jndi.InitialContextFactory
        	</activation-config-property-value>
        value>
	</activation-config-property>
        	<activation-config-property>
        	<activation-config-property-name>name</activation-config-property-name>
        	<activation-config-property-value>
                  openJMSQCF
        
		  openJMSQCF
	</activation-config-property-value>
        	</activation-config-property>
        	<activation-config-property>
        	<activation-config-property-name>
                destination
         </activation-config-property-name>
        	<activation-config-property-value>
                  queue1
        -value>
		  queue1
	</activation-config-property-value>
        	</activation-config-property>
    </activation-config>
    </message-driven>
    </enterprise-beans>
</openejb-jar>
</module>
<ext-module>
<connector>JMSRA_1</connector>
        	<external-path>jms/gerjmsexternaljms/1.0/rar </external-path>
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector" configId="jms.rar.1" 
parentId``parentId="jms.ear">

<resourceadapter>
...
    <outbound-resourceadapter>
       <connection-definition>
         <connectionfactory-interface>
            org.apache.geronimo.jms.connector.JMSQueueConnectionFactory
         </connectionfactory-interface>
           <connectiondefinition-instance>
             <name>JMSQueueFactory</name>
             <config-property-setting name="url">
                   tcp://localhost:3035
             </config-property-setting>
             <config-property-setting name="icf">
                   org.exolab.jms.jndi.InitialContextFactory
             </config-property-setting>
             <config-property-setting name="name">
                   openJMSTCF
             </config-property-setting>
             <connectionmanager>
             <no-transaction />
             <no-pool />
             </connectionmanager>
        </connectiondefinition-instance>
        </connection-definition>
       <connection-definition>
 ...
        </connection-definition>
</outbound-resourceadapter>
</resourceadapter>
<adminobject>
     <adminobject-interface>javax.jms.Queue</adminobject-interface>
     <adminobject-class>
        org.apache.geronimo.jms.connector.JMSQueueImpl
     </adminobject-class>
     <adminobject-instance>
          <message-destination-name>ivtQ</message-destination-name>
          <config-property-setting name="PhysicalName">
          queue1
          </config-property-setting>
      </adminobject-instance>
      </adminobject>
<adminobject>
...
</adminobject>
</connector>
<ext-module>
</application>

...

EJB Application

• Resource Adapter Name.
• Activation Spec Configuration.

Resource Adapter Instance

• Outbound.
  • Connection properties.
• Administered Objects.

Back to Top

Configuring WebSphereMQ

The following steps describe how you need to configure WebSphereMQ.

• Create a QueueManager ( GER_Q) in WebSphereMQ WMQ for Queues. A default local Queue is created called SYSTEM.DEFAULT.LOCAL.QUEUE.
• Create and start a Listener than listens on port 1414.
• Create and start a Server Connection Channel CHANNEL1.
• Create a QueueManager (GER_T) in WebSphereMQ WMQ for Topics and start it as broker from services.
• Create and start a Listener on port 1434 for this QueueManager.
• Create and start a Server Connection Channel CHANNEL1.
• Run MQSC command using the following file found in <WebSphereMQ_home>\java\bin\in <MQ_Install_Dir>/java/bin/MQJMS_PSQ.mqsc ( runmqsc pubsub.qmgr < MQJMS_PSQ.mqsc )
• Create JNDI bindings for QueueConnectionFactory and TopicConnectionFactory using JMSAdmin tool.
• Set the JMSAdmin.config to use File Context JNDI and point to C:/JNDI-Directory
• Run the JMSAdmin tool and create the following bindings:
  • QueueConnectionfactory
    DEF QCF(gerQCF) HOST(localhost) PORT(1414) CHANNEL(CHANNEL1) QMGR(GER_Q) TRAN(client)
    DEF Q(gerQ) QUEUE(SYSTEM.DEFAULT.LOCAL.QUEUE)

• • TopicConnectionFactory
    DEF TCF(gerTCF) HOST(localhost) PORT(14141434) CHANNEL(CHANNEL1) QMGR(GER_Q) TRAN(client)
    DEF Q(gerQ) QUEUE(SYSTEM.DEFAULT.LOCAL.QUEUE)

• • TopicConnectionFactory
    DEF TCF(gerTCF) HOST(localhost) PORT(1434) CHANNEL(CHANNEL1) QMGR(GER_T) TRAN(client)
    DEF T(gerTopic) TOPIC(SampleTopic)

Back to Top

Test Outbound Communication

• Using the deployed WAR we can check outbound communication to queue or topic.
• Go to http://localhost:8080/jms
• Enter details and press Queue or Topic
• The message is sent to PhysicalName for Queue - queue1 in OpenJMS and SYSTEM.DEFAULT.LOCAL.QUEUE in WebSphereMQ.
• For Topic the message is sent to topic1 or SampleTopic.
• A sample subscriber can be started to check if the message is received. WMQ has a sample program called JMSPubSub.java which can be used to run a subscriber to SampleTopic or topic1. This can be found in <WebSphereMQ_home>/Tools/Java/jms/PubSub.java

Test Inbound Communication

• The deployed MDB acts as EndPoint to messages posted in a Queue.
• Post a test message in Queue in WebSphereMQ ( SYSTEM.DEFAULT.LOCAL.QUEUE) or queue1 in OpenJMS.
• The onMessage of MDB should be invoked and u should see a message in Console of Geronimo.
• The same can be extended to Topic by adding another ActivationSpec for Topics.

References

The RA for JMS does not support XA. This can be added to make WebsphereMQ or OpenJMS part of distributed transactions in Geronimo.
There is a sample GenericJMS RA with XA support available in Sun java.net. This RA can be deployed in Geronimo to get XA support for JMS Providers. Visit the following link for further details, http://genericjmsra.dev.java.net

• • T) TRAN(client)
    DEF T(gerTopic) TOPIC(SampleTopic)

Back to Top

Test Outbound Communication

• Using the deployed WAR we can check outbound communication to queue or topic.
• Go to http://localhost:8080/jms
• Enter details and press Queue or Topic
• The message is sent to PhysicalName for Queue - queue1 in OpenJMS and SYSTEM.DEFAULT.LOCAL.QUEUE in WebSphereMQ.
• For Topic the message is sent to topic1 or SampleTopic.
• A sample subscriber can be started to check if the message is received. WMQ has a sample program called JMSPubSub.java which can be used to run a subscriber to SampleTopic or topic1. This can be found in <WebSphereMQ_home>/Tools/Java/jms/PubSub.java

Test Inbound Communication

• The deployed MDB acts as EndPoint to messages posted in a Queue.
• Post a test message in Queue in WebSphereMQ ( SYSTEM.DEFAULT.LOCAL.QUEUE) or queue1 in OpenJMS.
• The onMessage of MDB should be invoked and u should see a message in Console of Geronimo.
• The same can be extended to Topic by adding another ActivationSpec for Topics.

References

The RA for JMS does not support XA. This can be added to make WebsphereMQ or OpenJMS part of distributed transactions in Geronimo.
There is a sample GenericJMS RA with XA support available in Sun java.net. This RA can be deployed in Geronimo to get XA support for JMS Providers. Visit the following link for further details, http://genericjmsra.dev.java.net

Back to Top

Abbreviations

Resource Adapter - RA
WebsphereMQ - WMQ
Message Driven Bean - MDB

Attached Files

externaljms.ear - EAR application and Source Code that contains WAR for Outbound and MDB for Inbound from RA
externaljms-1.0.rar - JMS Rresource adapter and Source Code.
geronimo-application-mq.xml - Geronimo plan for MQ.
geronimo-application-openjms.xml - Geronimo plan for OpenJMS.Back to Top