JMS Input and Output Adapters

When the JMS Reader receives a message, it translates this message into a Tuple and when the JMS Writer receives a Tuple, it translates it into a JMS message. There are five JMS message types: BytesMessage, MapMessage, ObjectMessage, StreamMessage and TextMessage. Of these types, MapMessage is the one into which tuples translate most readily. Like a tuple, a MapMessage is a set of name-value pairs, making the translation of these two message types relatively straightforward. The JMS Reader includes a class that converts JMS MapMessages to StreamBase tuples, DefaultFromJMSMapMessageConverter. Similarly the JMS Writer adapter provides DefaultToJMSMapMessageConverter to translate from a Tuple to a JMS MapMessages.

StreamBase tuples and JMS MapMessages are essentially collections of name-value pairs. The JMS Reader pairs the fields held by a JMS MapMessage with fields in a StreamBase schema that have the same names and compatible types. If the name of a field in the MapMessage doesn't exist in the StreamBase schema then that field is dropped. Similarly, if the name of a field in the Schema doesn't exist in the MapMessage then there is no input value for that field and it is nulled.

In the case of the JMS Writer, all fields in the incoming Tuple are added to the MapMessage.

An interface is used to represent a class that can convert a JMS Message to a StreamBase tuple. This interface, com.streambase.sb.adapter.common.jms.enqueue.FromJMSMessageConverter, includes a method, Object convertFromJMSMessage(Message message) throws StreamBaseException that provides the implementation of the translation. A different translation class can be implemented, and the JMS Reader can then be configured to use this implementation. In this way, a converter to translate one of the other JMS message types can be specified, or an alternate implementation of a MapMessage converter can be specified.

As expected, the JMS Writer also provides a similar interface, com.streambase.sb.adapter.common.jms.dequeue.ToJMSMessageConverter which includes the Message convertToJMSMessage(Object object) throws StreamBaseException method to do the opposite conversion.

A JMS message consists of two primary pieces, a header and a payload (body). In addition, properties can be set on a JMS message.

By default, the JMS Embedded Adapters map the fields of a MapMessage to the fields of a StreamBase schema. The JMS Reader looks for entries in the payload of a MapMessage that have the same names as the fields of the StreamBase schema. The JMS Writer simply creates entries in the outgoing Message to match all the fields of the incoming StreamBase schema.

The JMS Embedded Adapters also provide facilities for handling other mappings, specified in the configuration file. For example, a name map can be used to map a field on a MapMessage to a field on a StreamBase schema that has a different name. Similarly, the fields in the header of a JMS message can be mapped to the fields of a StreamBase schema. In the same way, JMS properties can also be mapped to the fields of a StreamBase schema.

The JMS Reader consumes messages from JMS destinations. The manner in which these messages are acknowledged is configurable within the JMS Reader. The setting for the acknowledge mode can impact the performance of the reader.

The JMS Reader supports acknowledge modes of AUTO_ACKNOWLEDGE and DUPS_OK_ACKNOWLEDGE. The reader also supports the use of Tibco's proprietary acknowledge mode, NO_ACKNOWLEDGE. Of course, use of this acknowledge mode implies that Tibco's EMS message bus is being used with the reader. The acknowledge mode for a given JMS server is specified in the jms-server section of the configuration file, using the attribute acknowledge-mode.

Note also that the JMS Reader makes no effort to prevent or in any way handle the delivery of duplicate JMS messages. If a JMS server delivers the same message twice, the JMS Reader will simply consume it twice.

The JMS Writer will create JMS messages and deliver them to a JMS message bus. JMS messages can be delivered with either of two delivery modes, DeliveryMode.PERSISTENT or DeliveryMode.NON_PERSISTENT. The delivery mode for a JMS destination is specified in the destination section of the configuration file, using the delivery-mode attribute.

The semantics of JMS delivery modes is beyond the scope of this discussion. In general, a delivery mode of PERSISTENT implies a higher quality of service for the JMS destination. Some performance penalty is also implied, however. In particular, if a delivery mode of PERSISTENT is specified, and there are durable subscribers for the message, then the JMS message will need to be persisted before the JMS server can acknowledge the message producer.

The JMS Writer dequeues tuples from StreamBase streams, translates them into JMS messages, and routes them to JMS destinations. The adapter relies on two fields in the dequeued tuple to determine which destination on which JMS server to send the translated message. The two fields must be called __JMSServerName and __JMSDestinationName. These fields must contain the name of a configured JMS server and destination, respectively. These fields are optional if only one destination is specified in the configuration; they are required if the configuration specifies more than one destination (i.e., more than one server or more than one destination in a single server).

When one of the JMS Embedded Adapters executes, it needs to connect to an executing instance of a JMS message bus. Typically, this bus will be from one of the JMS providers. In order to connect to the JMS provider's JMS bus, JAR files provided by the JMS provider must be made available to the JMS Reader.

This is true whether the adapter is executing from within StreamBase Studio or from within StreamBase Server:

The JMS Embedded Adapters are configured using an XML configuration file. This configuration file consists of two types of information, JMS configuration and configuration concerning the translation of JMS messages to tuples and back.

It may be that many JMS destinations need to be specified in the configuration file for the JMS Embedded Adapters. Where applicable, it is possible to specify a default value for a configuration attribute of a destination. The default can then be overridden by specifying a value for a particular destination.

A sample configuration file, skeleton.sbconf is included with the JMS Reader sample that is included in the StreamBase distribution. This file includes comments describing the various XML elements and attributes that make up the configuration. This sample configuration file can be used as a template for configuration files. The skeleton configuration file can also be obtained by executing the jmsreader.jar JAR file. For Linux:

java -jar streambase-install-dir/lib/adapter/jmsreader.jar

For Windows:

java -jar "streambase-install-dir\lib\adapter\jmsreader.jar"

Similarly, the JMS Writer has a sample configuration file which can be displayed by executing the jmswriter.jar JAR file. For Linux:

java -jar streambase-install-dir/lib/adapter/jmswriter.jar

For Windows:

java -jar "streambase-install-dir\lib\adapter\jmswriter.jar"

Here are some typical settings for connecting to JMS servers from TIBCO EMS and ActiveMQ:

TIBCO EMS (using JNDI)

<jms-servers>
  <jms-server name="EMSServer" 
    provider-context-factory="com.naming.InitialContextFactory" 
    provider-url="tibjmsnaming://localhost:7222" 
    connection-factory-name="GenericConnectionFactory" 
    acknowledge-mode="NO_ACKNOWLEDGE"/>
</jms-servers>

ActiveMQ version 5.x (using JNDI)

<jms-servers>
  <jms-server name="ActiveMQServer" 
    provider-context-factory="org.apache.activemq.jndi.ActiveMQInitialContextFactory"
    provider-url="tcp://localhost:61616"
    connection-factory-name="org.apache.activemq.ActiveMQConnectionFactory"
    acknowledge-mode="NO_ACKNOWLEDGE"/>
</jms-servers>