Protocol extension for JMS

Overview

The protocol extension for JMS enables an application to communicate with an external JMS provider using the Connection API. The extension contains a connection protocol, jms, and a TypeHandler implementation that together allow an application to send and receive messages and work with their content, without using the JMS APIs directly.

Using the extension you can:

• Send messages to JMS queues or topics, using the POST operation.
• Receive messages from JMS queues, using the GET operation.
• Use connection destination configuration and connection handlers to monitor or manipulate messages being sent and received by the application.

To use the extension you must:

1. Include the zero.connection.jms dependency in your application ivy.xml.
2. Include the JMS provider's client implementation and javax.jms.* interface definitions to the application, either by adding another dependency or by placing the client JARs in the application lib directory.
3. Configure the JMS provider connection factories and destinations to make them available to the application using the Java Naming and Directory Interface (JNDI) API.
4. Configure the application zero.config with the information required to enable it to locate the connection factories and destinations using JNDI.

When the application has been configured correctly, the Connection API can be used to send and receive messages, without the application code needing to use the JMS API directly. For example a simple TextMessage can be sent to a JMS queue or topic represented by the connection destination, myQueue, using just the following code:

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

The GET operation can be similarly used to receive a message from a JMS queue:

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 getResponseBodyAsString() method extracts the contents of the JMS message. For example, if queue contained the TextMessage produced by the first example code extract, the value of result is the string, "This is my message text".

For these code samples to work, the application configuration in zero.config must contain two stanzas as outlined in the following pseudo-configuration:

/config/connection/jms/myConnection = {
    "initialContextFactory" : (context factory class name),
    "providerUrl" : (provider url),
    "connectionFactory" : (JNDI name of JMS connection factory)
}

/config/connection/destinations += {
   "myQueue" : {
       "connection" : {
           "protocol" : "jms",
           "config" : {
               "connectionConfig" : "myConnection",
               "destination" : (JNDI name of JMS destination)
           }
       }
    }
}

The first stanza defines the JNDI properties required to locate the JMS connection factory. The set of properties has been named myConnection. The second stanza defines the connection destination, myQueue, which was referenced in the previous Connection API examples. This connection destination has been bound to the jms protocol and indicates that the myConnection configuration should be used to locate the JMS connection factory.

Compatibility the IBM Reliable Transport Extension for WebSphere sMash

A single application can use both the protocol extension for JMS to communicate with an external JMS provider and the IBM Reliable Transport Extension for WebSphere sMash modules to communicate with a messaging broker.

More information

The following topics contain further information about this protocol extension:

• Configuring the connection to the JMS provider
• Working with javax.jms.Message objects
• Sending a JMS message from within a flow
• An example scenario using the protocol extension for JMS
• Connection jms protocol reference

For more information about using the Connection API and configuring connection destinations, see the Developer's Guide topics about the connection infrastructure included in the zero.core module.