Overview
With the release of IBM WebSphereMQ 6.0.2.1, IBM has provided a JCA 1.5 compliant resource adapter enabling integration with WebSphere MQ Series from any J2EE 1.4 compliant application server without the use of proprietary or custom integration code. This page details the process of deploying the IBM resource adapter for inbound and outbound JMS connectivity. The resource adapter supports connectivity to both WebSphereMQ version 6.0 and 5.3 (Client mode only).
Use of distributed transactions (XA) with the JMS resource adapter for both outbound and inbound connectivity requires the deployment of the Extended Transaction Client.
Notes on Installing Websphere MQ Trial Editions
If installing a Websphere MQ v6.x (WMQ) Trial Edition on Windows, watch out for the following (may also be relevant to other platforms and non-Trial editions):
- v6.0.0 does not contain the JCA adapter.
- Download v6.0.0, install it and then patch it with a "Fix" patch to bring it up to v6.0.2.1 (or higher) i.e. there's no v6.x+ installer, you need to install v6.0.0 and then patch it. This is not at all obvious from the IBM docs.
- Be sure to install the "Websphere Eclipse Platform" (WEP) before installing WMQ. The WMQ installer will allow you to install the WMQ Server without installing the WEP, but the resulting install is completely broken. Again, not at all obvious from the IBM docs.
- Note that the WEP installer is not in a separate distro. It is buried in the prereqs/IES dir of the expanded distro. Who knows why it is not auto-installed if it is mandatory and shipped with the distro!
- After installing the WEP and WMQ you'll have a runnable WMQ Server, but you'll still not have all you need to connect a client. The installed WMQ Server seems to be missing 2 jars that have to be downloaded separately from IBM. These are mqcontext.jar and com.ibm.mq.pcf.jar
Deploy the IBM JMS resource adapter
The IBM JMS resource adapter can be found in the following location from the WebSphereMQ 6.0.2.1 distribution:
MQ_HOME/Java/lib/jca/wmq.jmsra.rar
where MQ_HOME is the root of your IBM WebSphereMQ installation directory. Copy the wmq.jmsra.rar file to the deploy directory of your JBoss distribution to deploy the resource adapter.
If migrating from an existing IBM WebSphere MQ installation on JBoss, The following IBM WebSphereMQ jar files should be removed:
com.ibm.mq.jar
com.ibm.mqjms.jar
dhbcore.jar
These files are now provided by the IBM JMS resource adapter and must be removed to avoid versioning conflicts. A deployment error with code MQJCA1008 indicates this condition.
Create the WebSphereMQ Admin Object(s)
Prior to the release of the WebSphere MQ JMS resource adapter, destinations hosted by WebSphereMQ either had to be bound manually into JNDI or accessed via the WebSphereMQ IntialContext against the MQ host. The correct way to configure and manage destination objects using the JMS resource adapter is through the AdminObject facility provided by JCA 1.5. The following shows how this is accomplished via a standard JMX service deployment:
<server> <mbean code="org.jboss.resource.deployment.AdminObject" name="jboss.jca:service=WASDestination,name=QueueName"> <depends optional-attribute-name="RARName">jboss.jca:service=RARDeployment,name='wmq.jmsra.rar'</depends> <attribute name="JNDIName">JNDI_NAME</attribute> <attribute name="Type">javax.jms.Queue</attribute> <attribute name="Properties"> baseQueueManagerName=QM_NAME baseQueueName=BASE_QUEUE_NAME </attribute> </mbean> </server>
Placing this file into the JBoss deployment directory will create and bind a javax.jms.Queue destination into the JBoss JNDI tree. The QM_NAME and BASE_QUEUE_NAME should be replaced with values in your environment. The JNDI name can be anything, but it is generally a good practice to conform to standard naming conventions (ie queue/SomeQueuName).
Configure an MDB listening on a destination in WebSphereMQ
The MDB configuration
<enterprise-beans> <message-driven> <ejb-name>TestMDB</ejb-name> <ejb-class>org.jboss.test.TestListener</ejb-class> <messaging-type>javax.jms.MessageListener</messaging-type> <transaction-type>Container</transaction-type> <activation-config> <activation-config-property> <activation-config-property-name>destination</activation-config-property-name> <activation-config-property-value>DESTINATION_NAME</activation-config-property-value> </activation-config-property> <activation-config-property> <activation-config-property-name>destinationType</activation-config-property-name> <activation-config-property-value>DESTINATION_TYPE</activation-config-property-value> </activation-config-property> <activation-config-property> <activation-config-property-name>useJNDI</activation-config-property-name> <activation-config-property-value>false</activation-config-property-value> </activation-config-property> <activation-config-property> <activation-config-property-name>hostName</activation-config-property-name> <activation-config-property-value>MQ_HOST_NAME</activation-config-property-value> </activation-config-property> <activation-config-property> <activation-config-property-name>queueManager</activation-config-property-name> <activation-config-property-value>QUEUE_MANAGER_NAME</activation-config-property-value> </activation-config-property> </activation-config> </message-driven> </enterprise-beans>
While most of the above properties are self explanatory, notice the property
<activation-config-property> <activation-config-property-name>useJNDI</activation-config-property-name> <activation-config-property-value>false</activation-config-property-value> </activation-config-property>
By default (false) the JMS resource adapter will interpret the destination name as a Queue or Topic configured on WebSphereMQ. Setting this value to true will force the JMS resource adapter to acquire the JMS destination from the application server's JNDI namespace. Destinations can be bound into JNDI via the aforemention admin object facility described above.
Finally, the jboss.xml descriptor
<jboss> <enterprise-beans> <message-driven> <resource-adapter-name>wmq.jmsra.rar</resource-adapter-name> <ejb-name>TestMDB</ejb-name> <configuration-name>Standard Message Inflow Driven Bean</configuration-name> </message-driven> </enterprise-beans> </jboss>
WARNING: The above config uses standard jca inflow. If you are going to create your own configurations or invoker-proxy-bindings DO NOT use the JMS specific invoker proxy. The WSMQ resource adapter does not support all the standard properties, in particular it does not support
acknowledgeMode
or
subscriptionDurability
Configure a JMS connection factory
Configuration of a JMS connection factory is trivial using the standard ds.xml file mechanism
<tx-connection-factory> <jndi-name>JNDI_NAME</jndi-name> <xa-transaction></xa-transaction> <rar-name>wmq.jmsra.rar</rar-name> <connection-definition>javax.jms.ConnectionFactory</connection-definition> <config-property name="hostName" type="java.lang.String">QUEUE_MANAGER_HOST</config-property> <config-property name="queueManager" type="java.lang.String">QUEUE_MANAGER_NAME</config-property> <max-pool-size>20</max-pool-size> </tx-connection-factory>
No extended transactional client available
To receive inbound messages in a non-XA context, eg when you have not installed the extended transactional client, you must set the transaction attribute on the MDB to NOT_SUPPORTED (remember the default is REQUIRED).
If you do not do this the deploy will fail with the message:
javax.resource.ResourceException: MQJCA1004:Distributed transactions are unavailable.
Related
Comments