An example scenario using the protocol extension for JMS

Preparation

The steps that are required to set up the external Java™ Message Service (JMS) provider are outlined in this section. Consult the documentation for your JMS provider for more information.

Preparing to use IBM WebSphere MQ

The scenario assumes that the following preparation has been made:

1. IBM WebSphere MQ Version 6 has been installed and configured on the local machine.
2. A JMS queue connection factory and queue destination have been configured using the WebSphere MQ JMS administration tool, JMSAdmin.
3. The following WebSphere MQ classes for JMS from the WebSphere MQ Version 6 installation have been copied into in the lib directory of the example application:
   • com.ibm.mq.jar
   • com.ibm.mqjms.jar
   • jms.jar
   • jndi.jar
   • jta.jar
   • fscontext.jar
   • connector.jar
   • providerutil.jar
   • dhbcore.jar

Preparing to use IBM WebSphere Application Server

The scenario assumes that the following preparation has been made:

1. IBM WebSphere Application Server Version 6.1 has been installed and an application server profile has been started.
2. A JMS connection factory and queue destination have been configured using the application server default messaging provider and have been bound in JNDI.
3. The IBM Client for Java Message Service (JMS) on Java 2, Standard Edition (J2SE) with WebSphere Application Server has been downloaded from the IBM WebSphere Application Server support site and the included JARs are ready to be copied into in the lib directory of the example application:
   • sibc.jms.jar
   • sibc.jndi.jar

Creating the example application

1. Create a new IBM WebSphere sMash application, example.jms.
2. Add the zero.connection.jms dependency to the example.jms application.
3. Copy the appropriate JMS client JARs into the lib directory of the example.jms application.

Configuring the connection to the JMS provider

The configuration that is required to allow the example.jms application to locate the JMS connection factory is outlined in this section. Consult the documentation for your JMS provider for the required details.

Configuring a connection to IBM WebSphere MQ

Add the following stanza to the zero.config file of the example.jms application:

/config/connection/jms/myConnection = {
    "initialContextFactory" : "com.sun.jndi.fscontext.RefFSContextFactory",
    "providerUrl" : "file:/C:/JNDI-Directory",
    "connectionFactory" : "jms/myQCF"
}

The above example defines a connection factory configuration, myConnection, that uses the RefFSContextFactory initial context factory to look up resources bound in JNDI using the file, file:/C:/JNDI-Directory. The JMS connection factory is found by looking up the JNDI name, jms/myQCF.

Modify the initialContextFactory, providerUrl and connectionFactory parameters to suite the environment you have prepared using the WebSphere MQ JMS administration tool, JMSAdmin.

Configuring a connection to IBM WebSphere Application Server

Add the following stanza to the zero.config file of the example.jms application:

/config/connection/jms/myConnection = {
    "initialContextFactory" : "com.ibm.websphere.naming.WsnInitialContextFactory",
    "providerUrl" : "iiop://localhost:9810",
    "connectionFactory" : "jms/myQCF"
}

The above example defines a connection factory configuration, myConnection, that uses the JNDI provider for the WebSphere Application Server listening on port 9810 on the local machine and that uses the JNDI name jms/myQCF to look up the JMS connection factory.

Modify the providerUrl and connectionFactory parameters to suite your test environment.

Configuring the connection destination

Add the following stanza to the zero.config file of the example.jms application:

/config/connection/destinations += {
   "myQueue" : {
       "connection" : {
           "protocol" : "jms",
           "config" : {
               "connectionConfig" : "myConnection",
               "destination" : "jms/myQ",
               "userid" : "user1",
               "password" : "pass1",
               "timeout" : 5000 # timeout for GET operation
           }
       }
    }
}

The above example defines a connection destination, myQueue, to the Connection API. The destination is bound the the jms protocol and uses the connection factory configuration defined above, myConnection, to access the JMS queue that is bound to the JNDI name, jms/myQ. When establishing a JMS connection, the specified user ID and password is passed to the JMS provider. The timeout parameter specifies that the GET operation waits no longer than 5 seconds for a message to arrive on an empty queue.

Modify the destination, userid and password parameters to suite your test environment. Remove the userid and password parameters if your JMS connection is unauthenticated.

Using the jms connection protocol

The following code extract uses the Connection API to POST a String to the configured connection destination, myQueue:

try {
    Connection.doPOST("myQueue", "This is the message text");
} catch (Exception e) {
    // POST operation failed.
}

Following the configuration described in this topic, the protocol extension for JMS creates a TextMessage to carry the String payload and send it to the JMS queue named jms/myQ in JNDI.

The next example uses the Connection API to GET a message from the myQueue destination:

try {
    String result = Connection.doGET("myQueue").getResponseBodyAsString();
    // result contains JMS message text, or null if no message available
} catch (Exception e) {
    // GET operation failed.
}

The protocol extension for JMS tries to receive a message from the configured JMS queue and extract its payload as a String. For example, if the message was the TextMessage created by the first example, the result value is "This is my message text". If the queue is empty, the extension waits up to 5 seconds (as specified by the timeout parameter) for a message to become available. If no message arrives within this time, the value of result is null.