Chapter 12. Configuring a Java Message Service Provider

Procedure 12.1. Task

1. Go to the HornetQ Directory: cd SOA_ROOT/jboss-as/extras/hornetq.

2. Deploy It

   Run ant.

Procedure 12.2. Task

1. Configure the JMS Provider

   To configure JBoss Messaging, open the configuration file in a text editor: vi jboss-esb.xml.
2. Modify these settings:

   jndi-URL="localhost”
   	jndi-context-factory="org.jnp.interfaces.NamingContextFactory"
   	connection-factory="ConnectionFactory"
   	destination-type="queue"
   	destination-name="queue/myqueue"
   

   Important

   Always include the jboss-messaging-client.jar file on the class-path. (This file is found in the SOA_ROOT/jboss-as/client/jboss-messaging-client.jar archive.)

   Note

   If you want to use load balancing and fail-over capabilities, you must configure JBoss Messaging for clustering. This functionality is constantly evolving. To learn how to configure it, please consult the JBoss Messaging documentation.
3. Check that JBoss Messaging's Service Binding Manager configuration matches that found in the SOA_ROOT/seam/bootstrap/deploy/remoting-service.xml file.

Procedure 12.3. Task

1. Copy the IBM Websphere wmq.jmsra.rar file to the JBoss Enterprise SOA Platform: cp wmq.jmsra.rar SOA_ROOT/jboss-as/server/PROFILE/deploy/
2. Copy the IBM Websphere com.ibm.mqetclient.jar to the JBoss Enterprise SOA Platform: cp com.ibm.mqetclient.jar SOA_ROOT/jboss-as/lib/.
3. Open run.conf in your text editor: vi SOA_ROOT/jboss-as/bin/run.conf
4. Add this setting by modifying the JAVA_OPTS in run.conf:

   JAVA_OPTS="-DtraceEnabled=true -DtraceDestination=wmq_jca.trc 
       -DtraceLevel=10 -DlogWriterEnabled=false"
   

5. Save the file and exit.
6. Open the jboss-esb.xml file in your text editor: vi SOA_ROOT/jboss-as/server/PROFILE/deploy/jbossesb.esb/META-INF/jboss-esb.xml
7. Add these settings:

   <jms-jca-provider name="WMQ-JCA" connection-factory="MyAppXAConnectionFactory"
   adapter="wmq.jmsra.rar"
          jndi-URL="10.12.10.110:1414/CH1"
          jndi-context-factory="com.ibm.mq.jms.context.WMQInitialContextFactory">
       <property name="max-xa-sessions-per-connection" value="1" />
   <jms-bus busid="quickstartEsbChannel">
     <jms-message-filter dest-type="QUEUE" dest-name="Q1" transacted="true"/>
   </jms-bus>
   <activation-config>
        <property name="queueManager" value="QM1" />
        <property name="channel" value="CH1" />
        <property name="hostName" value="10.12.10.110" />
        <property name="port" value="1515" />
        <property name="transportType" value="CLIENT" />
        <property name="useJNDI" value="false" />
   </activation-config>
   </jms-jca-provider>
   

8. Save the file and exit.
9. Run crtmqm -q QM1
10. Run strmqm QM1

    define channel (CH.1) chltype (RCVR) trptype (TCP)
    start channel (CH.1)
    define qlocal (Q1)
    define listener(QM1.LISTENER) trptype(TCP) port(30001) ipaddr(10.12.58.110)
    start listener (QM1.LISTENER)
    

Procedure 12.4. Task

1. Run this command: /opt/mqm/java/bin/JMSAdmin -v

        
   java -Dcom.ibm.msg.client.commonservices.log.outputName=$MQ_JAVA_DATA_PATH/log -Dcom.ibm.msg.client.commonservices.trace.outputName=$MQ_JAVA_DATA_PATH/trace -DMQJMS_INSTALL_PATH=$MQ_JAVA_INSTALL_PATH com.ibm.mq.jms.admin.JMSAdmin $*
   

2. Open JMSAdmin.config in your text editor: vi JMSAdmin.config
3. Edit the file as per this sample code:

        
   INITIAL_CONTEXT_FACTORY=com.ibm.mq.jms.context.WMQInitialContextFactory
   
   PROVIDER_URL=localhost:30002/SYSTEM.DEF.SVRCONN
   
   SECURITY_AUTHENTICATION=none
   

   Note

   If you have a listener on a different port, use it instead. (The default is 1414).
4. Save the file and exit.
5. Define objects with these commands: InitCtx> def cf(ConnectionFactory) qmgr(QM1) tran(CLIENT) host(10.12.58.105) BROKERQMGR(QM1) and InitCtx> def qcf(QueueConnectionFactory) qmgr(QM1) tran(CLIENT) host(10.12.58.105)
6. If you are having problems with JMSAdmin, troubleshoot the logs: less /var/mqm/errors/AMQERR01.LOG and less /var/mqm/qmgrs/QUEUE MANAGER NAME/errors/AMQERR01.LOG

   Note

   For more information, refer to http://www.ibm.com/developerworks/websphere/techjournal/0502_woolf/0502_woolf.html.

Procedure 12.5. Task

1. Configure the Adapter

   The adapter name is wmq.jmsra.rar. Copy this file into the JBoss Enterprise SOA Platform's SOA_ROOT/jboss-as/server/PROFILE/deploy directory.

2. Check the Context Factory

   Ensure that the initial context factory is com.ibm.mq.jms.context.WMQInitialContextFactory.

3. Configure the QueueManager

   Ensure that the queueManager configuration is in the <activation-config>. You will need to configure a queue manager in your own Websphere MQ installation. (Note that all of your destination queues are configured in your queue manager.)

4. Configure the Channel

   Ensure that the channel configuration is in the <activation-config> property.

   Note

   You can configure a queue manager to use a number of different types of channel. Clients connect through server connection channels. A default server connection channel (SYSTEM.DEF.SVRCONN), is added as part of the Websphere MQ installation but it is a good idea to also create your own dedicated channels, especially if you are using extended (XA) transactions.

5. Configure the transportType

   Edit the transportType. The configuration for this is in the <activation-config> property. Websphere MQ supports two transport types ( Client and Binding).

6. Edit the Settings

   Open the configuration file in a text editor and edit it.
   Here is an example of a <jms-jca-provider> configuration. It shows how to set a gateway provider configuration:

   <jms-jca-provider adapter="wmq.jmsra.rar" connection-factory="MyAppXAConnectionFactory" jndi-context-factory="com.ibm.mq.jms.context.WMQInitialContextFactory" name="WMQ-JCA">
   	<property name="max-xa-sessions-per-connection" value="1"/>
   		<jms-bus busid="quickstartGwChannel">
   		<jms-message-filter dest-name="QUEUE1_JMS" dest-type="QUEUE" transacted="true"/>
   		</jms-bus>
   			<activation-config>
   				<property name="queueManager" value="TQM"/>
   				<property name="channel" value="Q1CONN"/>
   				<property name="hostName" value="localhost"/>
   				<property name="port" value="1414"/>
   				<property name="transportType" value="CLIENT"/>
   			</activation-config>
   </jms-jca-provider>
   

   Note

   It is actually the <jms-listener> configuration that determines the gateway/message-aware characteristics of a listener. However, as far as Websphere MQ is concerned, this is only of use as a gateway listener provider. In other words, this configuration would not work as a message-aware listener for Websphere MQ. This is because it does not specify an appropriate JNDI provider URL (as used by the ServiceInvoker) for routing ESB messages to the destinations (buses) defined on the provider.

7. Configure the JCA Adapter

   The <activation-config> configures the JCA adapter so that it obtains messages from the destinations. It does not determine how messages are to be delivered to the destinations. Here is an example of a configuration that could be used as a message-aware listener's provider:

   <jms-jca-provider adapter="wmq.jmsra.rar" connection-factory="MyAppXAConnectionFactory" jndi-URL="localhost:1414/CHANX" jndi-context-factory="com.ibm.mq.jms.context.WMQInitialContextFactory" name="WMQ-JCA">
   	<property name="max-xa-sessions-per-connection" value="1"/>
   		<jms-bus busid="quickstartEsbChannel">
   			<jms-message-filter dest-name="QUEUE2_JMS" dest-type="QUEUE" transacted="true"/>
   		</jms-bus>
   	<activation-config>
   		<property name="queueManager" value="TQM"/>
   		<property name="channel" value="Q2CONN"/>
   		<property name="hostName" value="localhost"/>
   		<property name="port" value="1414"/>
   		<property name="transportType" value="CLIENT"/>
   	</activation-config>
   </jms-jca-provider>
   

8. Creating a Standard JMS Provider

   The settings for creating a standard JMS provider configuration are similar:

   <jms-provider connection-factory="MyAppConnectionFactory" jndi-URL="localhost:1414/CHAN1" jndi-context-factory="com.ibm.mq.jms.context.WMQInitialContextFactory" name="JMS">
   	<jms-bus busid="quickstartGwChannel2">
   		<jms-message-filter dest-name="QUEUE3_JMS" dest-type="QUEUE"/>
   	</jms-bus>
   </jms-provider>
   

   Note

   With the standard provider, there is neither an adapter nor any <activation-config> configurations. Listeners receiving messages from the destinations defined in a standard provider do not use a JCA Adapter Inflow to obtain the messages. Instead, they need to use JNDI to find the destination and obtain the messages. This means that, for Websphere MQ, the jndi-URL must always be specified (remember that for JCA it is only required for destinations that service a Message-Aware listener).

9. Save

   Save the file and exit.

Procedure 12.6. Task

1. Edit the JMSRouter Configuration

   Open the JMSRouter's configuration file in a text editor and modify the settings in your jboss-esb.xml. Here is an example of a JMSRouter configuration for routing messages to Websphere MQ from inside an ESB action pipeline:

   <action class="org.jboss.soa.esb.actions.routing.JMSRouter" name="routeToORDERSQueue">
   	<property name="jndi-context-factory" value="com.ibm.mq.jms.context.WMQInitialContextFactory"/>
   	<property name="jndi-URL" value="wmqserver:1414/CHANX"/>
   	<property name="connection-factory" value="WMQConnectionFactory"/>
   	<property name="jndiName" value="ORDERS"/>
   </action>
   

2. Save

   Save the file and exit.

Procedure 12.7. Task

1. Edit the jms-jca-provider Configuration

   Edit the jboss-esb.xml file in a text editor. Here is how the jms-jca-provider configuration would look for an Extended Transaction Client configuration. (In this example, the XA Connection Factory that has been configured in the WMQ JNDI namespace is called WMQXAConnectionFactory.)

   Note

   Inflow related configurations (adapter, <activation-config> etc) were intentionally omitted as they are not relevant to the Extended Client configuration:

   <jms-jca-provider name="WMQ" connection-factory="WMQXAConnectionFactory"
   	jndi-URL="wmqserver:1414/CHANXA_SEND"
   	jndi-context-factory="com.ibm.mq.jms.context.WMQInitialContextFactory">
   		<property name="max-xa-sessions-per-connection" value="1" />
   			<jms-bus busid="ordersGwChannel">
   			<jms-message-filter dest-type="QUEUE" dest-name="ORDERS" transacted="true"/>
   			</jms-bus>
   				<activation-config>
   					<!--
   					Used by inflow... not relevant to client
   					See section on JMS and JCA.
   					-->
   		</activation-config>
   </jms-jca-provider>
   

2. Configuring for Use with the JMSRouter

   This example shows how to use the same XA Connection Factory on the JMSRouter:

   <action name="routeToORDERSQueue" class="org.jboss.soa.esb.actions.routing.JMSRouter">
   <property name="jndi-context-factory"
   value="com.ibm.mq.jms.context.WMQInitialContextFactory"/>
   <property name="jndi-URL" value="wmqserver:1414/CHANXA_SEND"/>
   <property name="connection-factory" value="WMQXAConnectionFactory"/>
   <property name="jndiName" value="ORDERS"/>
   <property name="max-xa-sessions-per-connection" value="1"/>
   <!-- etc... -->
   </action>
   

   Important

   An important point to note about Websphere MQ and XA is that it does not support both getting and putting messages concurrently on the same Queue Manager Channel. For this reason, it is a good idea to configure a dedicated channel for each component that gets or puts messages into a Websphere MQ destination in the context of XA transactions.
3. Set the max-xa-sessions-per-connection property in jboss-esb.xml to 1.

4. Save

   Save the file and exit.
5. Configure a dedicated queue manager channel for each component that obtains or sends messages to a Websphere MQ destination.
6. Make sure the GET and PUT properties on each of the Websphere MQ destinations are not set to Inhibit. (This can be happen when the destination is created and it results in the ESB being unable to obtain or send messages.)

Procedure 12.8. Task

1. Navigate to the bin directory: cd /opt/mqm/java/bin.
2. Launch JMSAdmin.
3. Use this program to administer your JNDI settings and obtain a ConnectionFactory for Plain JMS interactions.

   Note

   For more information about using JMSAdmin, refer to http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp.

Procedure 12.9. Task

1. Make a queue manager called QM1: crtmqm -q QM1
2. Start runmqsc: runmqsc QM1
3. Input the following settings when prompted:

   define channel (CH.1) chltype (RCVR) trptype (TCP)
   start channel (CH.1)
   define qlocal (Q1)
   define listener(QM1.LISTENER) trptype(TCP) port(30001) ipaddr(10.12.58.110)
   start listener (QM1.LISTENER) 
   (end)
   

4. Exit the program.
5. Copy com.ibm.mqetclient.jar from your Websphere MQ installation to your server: cp com.ibm.mqetclient.jar SOA_ROOT/jboss-as/PROFILE/lib/
6. Copy wmq.jmsra.ivt.ear from your Websphere MQ installation to your server: cp wmq.jmsra.ivt.ear SOA_ROOT/jboss-as/server/PROFILE/deploy
7. Copy wmq.jmsra.rar from your Websphere MQ installation to your server: cp wmq.jmsra.rar SOA_ROOT/jboss-as/server/PROFILE/deploy
8. Create a data source file in a text editor (be sure to change the IP address to that of your WSMQ server): vi SOA_ROOT/jboss-as/server/PROFILE/deploy/wsmq-ds.xml
   Here is a sample configuration:

   <?xml version="1.0" encoding="UTF-8"?>
   
    
   
   <connection-factories>
     <!-- connection factory definition -->
     <tx-connection-factory>
   
    
   
       <jndi-name>IVTCF</jndi-name>
       <xa-transaction />
       <rar-name>wmq.jmsra.rar</rar-name>
   
    
   
       <connection-definition>
         javax.jms.ConnectionFactory
       </connection-definition>
   
    
   
       <config-property name="channel" type="java.lang.String">SYSTEM.DEF.SVRCONN</config-property>
       <config-property name="hostName" type="java.lang.String">
         10.12.58.110
       </config-property>
       <config-property name="username" type="java.lang.String">mqm</config-property>
       <config-property name="password" type="java.lang.String">mqm</config-property>
       <config-property name="port" type="java.lang.String">30001</config-property>
       <config-property name="queueManager" type="java.lang.String">QM1</config-property>
       <config-property name="transportType" type="java.lang.String">CLIENT</config-property>
   
    
   
       <security-domain-and-application>JmsXARealm</security-domain-and-application>
     </tx-connection-factory>
   
    
   
     <!-- admin object definition -->
     <mbean code="org.jboss.resource.deployment.AdminObject"
         name="jca.wmq:name=ivtqueue">
   
    
   
       <attribute name="JNDIName">
         IVTQueue
       </attribute>
       <depends optional-attribute-name="RARName">
         jboss.jca:service=RARDeployment,name='wmq.jmsra.rar'
       </depends>
       <attribute name="Type">javax.jms.Queue</attribute>
   
    
   
       <attribute name="Properties">
         baseQueueManagerName=QM1
         baseQueueName=Q1
       </attribute>
     </mbean>
   </connection-factories>
   

9. Save the file as and exit your text editor.
10. Launch a web browser and go to http://localhost:8080/WMQ_IVT/.
    This brings up the IVT ("Install Verification Test").
11. Run the normal test and the transactional test.

    Note

    For more information, refer to http://www.ibm.com/developerworks/websphere/library/techarticles/0710_ritchie/0710_ritchie.html.

Procedure 12.10. Task

1. Open the run.conf File

   Open the file in a text editor: vi SOA_ROOT/jboss-as/bin/run.conf.

2. Edit the run.conf File

   Appending the following lines onto the end of the file:

   # Settings to enable WebSphere MQ resource adapter trace
   JAVA_OPTS="$JAVA_OPTS -DtraceEnabled=true -DtraceDestination=wmq_jca.trc
   -DtraceLevel=10 -DlogWriterEnabled=false"
   

3. Enable Client Logging

   Still in the text editor, set the MQJMS_TRACE_LEVEL property:

   # Settings to enable WebSphere MQ resource adapter and client trace
   JAVA_OPTS="$JAVA_OPTS -DtraceEnabled=true -DtraceDestination=wmq_jca.trc
   -DtraceLevel=10 -DlogWriterEnabled=false -DMQJMS_TRACE_LEVEL=base"
   

4. Save

   Save the file and exit.

Procedure 12.11. Task

• Call the enableTrace Static Method

  Call the com.ibm.mq.MQEnvironment's enableTrace static method.

Procedure 12.12. Task

1. Edit the Configuration

   Open the configuration file in a text editor: vi SOA_ROOT/jboss-as/server/PROFILE/deploy/jbossesb.esb/META-INF/jboss-esb.xml.
2. Add these parameters:

   <property name="jndi-prefixes" value="connectionFactory. , destination"/>
   <property name="jndi-connection-factory" value="org.apache.qpid.jndi.PropertiesFileInitialContextFactory"/>
   <property name="connectionFactory.qpidConnectionFactory" value="amqp:// guest:guest@clientid/virtualHost?brokerlist='tcp://localhost:5672'"/>
   <property name="destination.[queueName]Queue" value="direct://amq.direct//[queueName]? routingkey=[routingkeyname]"/>
   

3. Save

   Save the file and exit.

4. Add the Requisite Files to the Class-Path

   Add these .JAR files to the classpath:
   • qpid-common-0.6.jar
   • qpid-client-0.6.jar

Procedure 12.13. Task

1. Edit the Configuration

   Open the configuration file in a text editor (vi SOA_ROOT/jboss-as/server/PROFILE/deploy/jbossesb.esb/META-INF/jboss-esb.xml) and set these parameters:

   jndi-URL="tcp://localhost:7222”
   jndi-context-factory=”com.tibco.tibjms.naming.TibjmsInitialContextFactory"
   connection-factory="QueueConnectionFactory"
   destination-type="queue"
   destination-name="myqueue"
   

2. Save

   Save the file and exit.

3. Add the Requisite Files to the Class-Path

   Add these .JAR files to the classpath (they are located in the tibco/ems/clients/java directory):
   • jaxp.jar
   • jndi.jar
   • tibcrypt.jar
   • tibjmsapps.jar
   • tibrvjms.jar
   • jms.jar
   • jta-spec1_0_1.jar
   • tibjmsadmin.jar
   • tibjms.jar

1. To configure the settings, open the properties file: vi SOA_ROOT/jboss-as/server/PROFILE/deploy/jbossesb.sar/jbossesb-properties.xml
2. Locate the following lines:

   <property name="org.jboss.soa.esb.registry.queryManagerURI" value="org.apache.juddi.registry.local.InquiryService#inquire"/>
   <property name="org.jboss.soa.esb.registry.lifeCycleManagerURI" value="org.apache.juddi.registry.local.PublishService#publish"/>
   

   Change them to this:

   <property name="org.jboss.soa.esb.registry.queryManagerURI" value="http://<server-name>:9901/uddi/inquiry_v2"/>
   <property name="org.jboss.soa.esb.registry.lifeCycleManagerURI" value="http://<server-name>:9901/uddi/publish_v2"/>
   <property name="org.jboss.soa.esb.registry.uddi.maxRows" value="100"/>
   

3. Edit the queryManagerURI and the lifeCycleManagerURI to match the URLs from your installation of SOA Workbench:

   <property name="org.jboss.soa.esb.registry.uddi.maxRows" value="100"/>
   <property name="org.jboss.soa.esb.registry.queryManagerURI" value="http://<server-name>:9901/uddi/inquiry_v2"/>
   <property name="org.jboss.soa.esb.registry.lifeCycleManagerURI" value="http://<server-name>:9901/uddi/publish_v2"/>
   

4. Locate this line:

   <property name="org.jboss.soa.esb.scout.proxy.transportClass" value="org.apache.ws.scout.transport.LocalTransport"/>
   

   Change it to this:

   <property name="org.jboss.soa.esb.scout.proxy.transportClass" value="org.apache.ws.scout.transport.AxisTransport"/>
   

5. Within jbossesb-properties.xml, change this to match the SOA Workbench username and password that you will be using:

   <property name="org.jboss.soa.esb.registry.user" value="administrator"/>
   <property name="org.jboss.soa.esb.registry.password" value="password"/>
   

6. Save the file and exit.

1. Download axis-bin-1_4.tar.gz from http://ws.apache.org/axis/ and extract axis-1.4.jar and commons-discovery-0.2.jar (or later).
2. Copy these two files into the lib directory: cp *jar SOA_ROOT/jboss-as/server/PROFILE/lib.

1. To apply the guest role to a guest user to grant anonymous access, go into the Organization Tree and click on the top-level registry node in the SOA Workbench hierarchy.

   Note

   SOA Workbench is a section of the SOA Service Manager Registry that acts as a third party UDDI registry provider.
2. Click on the second-level “Security” tab (within the Workbench hierarchy).
3. Click “Manage Role” for “Guest” under “Role Memberships.
4. Search for the user “guest”.
5. Select the checkbox next to “guest” and click “Apply".

1. To change the workflow so that services are published upon creation, click on the “Configure” tab and then select “Workflow”.
2. View the Workflow Definition, save it to your local disk, and then change the function type line under @create to <function type="publish" /> and the step attribute to “100”.
3. Save this.
4. Update the workflow to the local copy you have just saved.

• Use the "Search" option to find services. This feature also displays information about each service, including a description, its current state, its version number and the number of alerts it has generated. Services are registered in the SOA Service Workbench so manage them directly through its graphical user interface.

• If you encounter an error when configuring and updating the Workflow, you can verify it has been modified correctly by checking that its configuration has changed from the original configuration (which looked like this):

  <action id="1" name="@create">
  	<results>
  		<unconditional-result old-status="Created" status="Draft" step="100" owner="${caller}"/>
  	</results>
  	<post-functions>
  		<function type="setLifecycleStage">
  			<arg name="stage">Design</arg>
  			</function>
  	</post-functions>
  </action>
  

  Rather, it should now look like this:

  <action id="1" name="@create">
  	<results>
  		<unconditional-result old-status="Created" status="Draft" step="100" owner="${caller}"/>
  		</results>
  		<post-functions>
  			<function type="publish">
  		</function>
  	</post-functions>
  </action>