JMS Legacy Input And Output Adapters Sample

Contents

Introduction
Running This Sample in StreamBase Studio
Running This Sample in Terminal Windows
Importing This Sample into StreamBase Studio
Sample Location

Note

This document describes an outdated and deprecated set of JMS adapters. To use StreamBase's most up-to-date and fully supported JMS connectivity solution, seeUsing the JMS and TIBCO EMS Operators and associated samples JMS and EMS Adapter Samples.

Introduction

This sample demonstrates the use of the TIBCO StreamBase® Adapter for JMS. The input adapter subscribes to JMS destinations, receives JMS Messages, and transforms them into StreamBase tuples. The tuples are then sent to one or more downstream operators. Similarly, tuples may be sent to a JMS output adapter to be sent as JMS messages to a JMS destination.

Note

As shipped, this sample is not completely configured. You must edit the provided sbd.sbconf file and specify the path to the JAR file that provides client access to your JMS server. The file has a commented-out example of the path to the TIBCO EMS JAR file, when installed in its standard location.

You must also edit the jmsreader.jmsconf and jmswriter.jmsconf to provide site-specific information, such as the hostname of your JMS server. As shipped, these files are configured for a TIBCO EMS server.

This sample needs to run with a JMS implementation. The sample and the adapter itself are not specific to TIBCO EMS and will run against any JMS compliant implementation.

This sample includes a trivial StreamBase application, and works as follows:

A JMS Writer adapter connects to the running JMS server, subscribes to its topics, and waits to receive tuples to convert them to JMS MapMessages. It then sends those messages to the JMS server.
A JMS Reader adapter connected to the same JMS server and subscribed to the same topics will receive those messages, convert them back to tuples and route them to different output streams based on the value of the symbol field.
To send tuples to the JMS Writer, a feed simulation file (called messagesToSendToJMS.sbfs) has been provided. When the simulation is run, tuples will be automatically generated and sent to the JMS Writer, at the default rate of two tuples per second.

Three configuration files are included with this sample:

sbd.sbconf, the configuration file for StreamBase Server.
jmsreader.jmsconf, the configuration file for the JMS reader adapter.
jmswriter.jmsconf, the configuration file for the JMS writer adapter.

In addition, fully-commented skeleton configuration files are included in the configurationFileReference subdirectory to demonstrate the possible settings.

By default, the sample is configured to run against TIBCO EMS. The configuration may need to be changed for your site's JMS implementation.

JMS Server

This sample publishes JMS messages to a JMS message bus. This means that at least one message bus needs to be configured and running. In the included configuration files, one JMS server (named tibcoServer in the adapter configuration files) is referenced. The jmsreader.jmsconf and jmswriter.jmsconf configuration files may need to be changed to reference a JMS server at your site.

The creation of destinations on a JMS message bus is not discussed in detail here. However, the configuration file for the JMS reader adapter does reference specific JMS destinations. The set of JMS destinations referenced is included in a file named topics.sample.conf. The JMS message bus being used to run the sample will need to create this set of destinations when it starts up, otherwise the sample code will not execute correctly.

StreamBase Application

The sample application has three distinct part. One part, the feed simulator, automatically generates tuples to be converted and sent to JMS. The second part receives those tuples, converts them to JMS messages and sends them to the JMS server. The final part reads the messages back from the JMS server, converts them back into tuples and routes them to one of several output streams based on the value of one of the fields.

Feed Simulator

A feed simulation definition file (messagesToSendToJMS.sbfs) is provided with the application. When run (either from StreamBase Studio or from the sbfeedsim utility in a console) it will automatically generate tuples and send them to the TuplesDestinedToJMS input stream in the application.

JMS Writer Adapter

Once a tuple is handed to the TuplesDestinedToJMS input stream it is read by a Map operator that adds certain necessary fields to make the tuple ready for sending to the JMS Writer adapter. In particular, the Map operator creates a __JMSServerName field with a value set to the name of the JMS server defined in the JMS Writer adapter's configuration file. It also adds a field called __JMSDestinationName with a value derived from the value of the tuple's symbol field. The adapter then reads the tuple, converts it to a JMS MapMessage and sends it to the JMS server's destination specified by the __JMSDestinationName field.

JMS Reader Adapter

Once the message has been sent to the JMS destination the JMS Reader adapter reads it back and converts it back to a tuple. From there it is sent to a Filter operator which will route the tuple to the appropriate Output stream based on the value of the symbol field.

Running This Sample in StreamBase Studio

A JMS implementation has not been included with the sample. In order to run the sample, a JMS implementation must be available. By default, the sample is configured to run with the TIBCO implementation of JMS, called EMS. However, this procedure can also be used with a different JMS implementation.

In the project created when you load this sample into StreamBase Studio, a file named topics.sample.conf is imported. This is the set of topics that the JMS server should include when it is started. You may need to copy topics.sample.conf to a location where your JMS server can find it. For EMS, this location is $TIBCO_HOME/ems/bin/topics.conf, or %TIBCO_HOME%\ems\bin\topics.conf on Windows. For other JMS implementations you may need to follow different procedures to add the required topics; please refer to your JMS provider's documentation for instructions on how to proceed.
The JMS implementation you use should provide one or more implementation JAR files, for example tibjms.jar from TIBCO, which enables the sample to be run with the TIBCO implementation of the JMS message bus, EMS. These JAR files must be added to the sample project's Referenced Libraries.

Important

Regardless of the JMS vendor used, you must also provide a copy of jms.jar. This file should be included in your JMS vendor's product installation alongside its other JAR files such as those mentioned above.
Start the JMS server. For EMS, change directory to $TIBCO_HOME/ems/bin (%TIBCO_HOME%\ems\bin on Windows), and execute tibemsd.
You may need to edit jmsreader.jmsconf and jmswriter.jmsconf files to specify the site specifics of your JMS server. To do so, double-click the file in the Package Explorer. By default, both files include configuration settings for TIBCO EMS.
In the Package Explorer, double-click jms-sample.sbapps to open the application in the EventFlow Editor.
Select the JMSAdapter icon to open its Properties view, then select the Adapter Settings tab. There are only two properties for the JMS Reader. In the Configuration file control, specify jmsreader.jmsconf, the configuration file for this instance of the JMS Reader. The other property controls the verbosity level used by the adapter when issuing console messages.
Make sure the jms-sample.sbapp application is the currently selected and active tab in the EventFlow Editor, then click the Run toolbar button. This starts the application and switches to the SB Test/Debug perspective.
Run the feed simulation to send tuples to the JMS Writer adapter. In the Feed Simulations tab, select messagesToSendToJMS.sbfs and click the run button at the bottom left of the tab. This will cause the application to start sending tuples to the TuplesDestinedToJMS stream at regular intervals.
Observe tuples displayed in the Application Output view after the feed simulation is started.
When done, press F9 or click the Stop Running Application button.

Running This Sample in Terminal Windows

This section describes how to run the sample in UNIX terminal windows or Windows command prompt windows. On Windows, be sure to use the StreamBase Command Prompt from the Start menu as described in the Test/Debug Guide, not the default command prompt.

In the project that is created when you load the sample into StreamBase Studio, a file named topics.sample.conf is imported. This is the set of topics that the JMS server should include when it is started. You may need to copy topics.sample.conf to a location where the JMS server can find it. For EMS, this location is $TIBCO_HOME/ems/bin/topics.conf, or %TIBCO_HOME%\ems\bin\topics.conf on Windows. For other JMS implementations you may need to follow different procedures to add the required topics; please refer to your JMS provider's documentation for instructions on how to proceed.
Start the JMS server. For EMS, change directory to $TIBCO_HOME/ems/bin (%TIBCO_HOME%\ems\bin on Windows), and execute tibemsd.
You may need to edit jmsreader.jmsconf and jmswriter.jmsconf files to specify the site specifics of your JMS server. To do so, double-click the file in the Package Explorer. By default, both files include configuration settings for TIBCO EMS.
Open three terminal windows on UNIX, or three StreamBase Command Prompts on Windows. In each window, navigate to the directory where the sample is installed or to your workspace copy of the sample, as described above.
Configure the StreamBase Server configuration file, sbd.sbconf, which is included as part of the sample.

The JMS implementation you use should provide one or more implementation JAR files. To make these files available to StreamBase Server when it starts, you must reference them in the <java-vm> section of the sbd.sbconf file, in one or more <jar> directives. An entry for the TIBCO EMS implementation file, tibjms.jar, is already included in sbd.sbconf.

Important

Regardless of the JMS vendor used, you must also provide a copy of jms.jar. This file should be included in your JMS vendor's product installation alongside its other JAR files such as those mentioned above.
In one of the terminal windows, start the StreamBase Server using the -f option to reference the configuration file. For example:
```
sbd -f sbd.sbconf jms-sample.sbapp
```
From the second terminal window, dequeue from one or more output streams. There are three output streams, GOOG_OUT, EBAY_OUT and YHOO_OUT. To dequeue from one or more of these, enter an sbc command like the following example, each in its own terminal window:
```
sbc dequeue EBAY_OUT
```
Alternatively, you may dequeue from ALL output streams with the following command:
```
sbc dequeue --all
```
Publish some messages to the JMS server. To do so, in the third terminal window invoke the standalone feed simulator, sbfeedsim, with the included feed simulation definition file as a parameter:
```
sbfeedsim messagesToSendToJMS.sbfs
```
Tuples are now displayed in the window running the sbc dequeue command after the publisher is started.
Type the following command to terminate the server and dequeuer:

sbadmin shutdown

Importing This Sample into StreamBase Studio

In StreamBase Studio, import this sample with the following steps:

From Studio's top menu, select File → Load StreamBase Sample.
Type jms in the Search field to narrow the list of samples.
Select the Legacy JMS/EMS sample from the StreamBase Messaging Adapters category.
Click OK.

StreamBase Studio creates a single project containing the sample files.

Sample Location

When you load the sample into StreamBase Studio, Studio copies the sample project's files to your Studio workspace, which is normally part of your home directory, with full access rights.

Important

Load this sample in StreamBase Studio, and thereafter use the Studio workspace copy of the sample to run and test it, even when running from the command prompt.

Using the workspace copy of the sample avoids the permission problems that can occur when trying to work with the initially installed location of the sample. The default workspace location for this sample is:

studio-workspace/sample_adapter_embedded_jmsreader

See Default Installation Directories for the location of studio-workspace on your system.

In the default TIBCO StreamBase installation, this sample's files are initially installed in:

streambase-install-dir/sample/adapter/embedded/jmsreader

See Default Installation Directories for the location of streambase-install-dir on your system. This location may require administrator privileges for write access, depending on your platform.