JMS Input Adapter Sample

Introduction

The StreamBase JMS Reader 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.

The JMS Reader sample needs to run along with a JMS implementation. By default the sample is configured to run with an installation of the TIBCO EMS server. However, the sample and the adapter itself are not specific to EMS and will run against any other JMS compliant implementation.

This sample includes a trivial StreamBase application. In this application a filter is downstream of the JMS reader adapter. This filter routes tuples to different output streams based on the value of a field in the tuple; in this example the field ticker_symbol is used.

A Java class, JMSPublisher, is used to initially publish JMS messages to the set of configured JMS destinations. The JMSPublisher class can be invoked either by a launch configuration in StreamBase Studio, or by the sb-ems-publish program, which is included in the StreamBase distribution but runs independently of StreamBase Studio. This publisher reads messages from a file, messages.txt, creates JMS messages from them, and then publishes them.

Three configuration files are included with this sample:

sbd.sbconf, the configuration file for the StreamBase Server itself. A version of sbd.sbconf is included and should work for this sample.
jmsreader.sbconf is used to configure the JMS reader adapter.
jms-publisher.sbconf is used to configure the JMS publisher program, invoked by either StreamBase Studio or sb-ems-publish.

By default, both the reader and publisher are configured to run against TIBCO EMS. Their configuration may need to be changed for your site. Keep in mind that some aspects of the configuration need to be consistent between jmsreader.sbconf and jms-publisher.sbconf.

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, is referenced. The configuration of the server 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 probably need to create this set of destinations when it starts up. Otherwise, the sample code will not execute correctly.

JMS Publisher

Once all the other executables are running, the publisher can be used to publish messages.

The publisher reads messages from a text file. A messages file, messages.txt, is provided with the sample. The messages file holds a series of messages, one per line. Each message consists of a series of entries, the entries are separated by a pound sign (#) delimiter.

For each message, two initial entries are expected: the name of the JMS server to use, and the name of the JMS destination to publish to. The name of the JMS server must match the name of a server specified in the configuration file for the publisher. Similarly, the destination name should match the name of a destination that is known to this JMS server.

A series of data entries follows these two initial entries. Each set of three entries specifies a field to be included in a JMS MapMessage. The three entries specify, in turn, the name of the JMS field, the type of the JMS field, and the value of the JMS field.

An entry in the messages file might look something like this:

tibcoServer#destination1#bid_value#java.lang.Double#10.5

Eventually, each message in the messages file will be transformed into a tuple. The names in the messages file will eventually become the names of the fields in a StreamBase schema. Essentially, then, the names of the fields in the messages file need to match the names of the fields in the schema created for the JMS Reader adapter.

Importing This Sample into StreamBase Studio

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

From the top menu, click File → Load StreamBase Sample.
Select this sample from the Embedded Adapters list.
Click OK.

StreamBase Studio creates a single project containing the sample files.

Sample Location

By default, the sample files are installed in:

On Windows: C:\Program Files\StreamBase Systems\StreamBase.n.m\sample\adapter\embedded\jmsreader\
On UNIX: /opt/streambase/sample/adapter/embedded/jmsreader/

When you load the sample into StreamBase Studio, Studio copies the sample project's files to your Studio workspace. StreamBase Systems recommends that you use the workspace copy of the sample, especially on UNIX, where you may not have write access to /opt/streambase. In the default installation, the path to this sample in your Studio workspace is:

UNIX:       
  ~/streambase-studio-n.m-workspace/sample_adapter_embedded_jmsreader
Windows XP:
  C:\Documents and Settings\username\My Documents\StreamBase Studio n.m Workspace\
      sample_adapter_embedded_jmsreader
Windows Vista:
  C:\Users\username\Documents\StreamBase Studio n.m Workspace\
      sample_adapter_embedded_jmsreader

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.
The JMS implementation you use should provide one or more implementation JAR files. The sample includes tibjms.jar, which enables the sample to be run with the TIBCO implementation of the JMS message bus, EMS.
Start the JMS server. For EMS, change directory to $TIBCO_HOME/ems/bin (%TIBCO_HOME%\ems\bin on Windows), and execute tibemsd.
In the Package Explorer, double-click jms-sample.sbapp to open the application in the EventFlow Editor.
You may need to edit jmsreader.sbconf file to specify the site specifics of your JMS server. To do so, double-click the file in the Package Explorer. By default, the file includes configuration settings for TIBCO EMS.
Select the JMSAdapter icon to open its Properties view, then select the Adapter Settings tab. There is only one property for the JMS Reader. In the Configuration file control, specify jmsreader.sbconf, the configuration file for this instance of the JMS Reader.
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.
Publish some messages to the JMS server. Messages should be published to the same destinations that the sample application subscribes to.

A StreamBase Studio launch configuration, JMSPublisher.launch, is included with the sample, together with the necessary Java classes. To publish messages to the JMS server, run the JMSPublisher launch configuration as follows:
- Select Run → Open Run Dialog.
- The JMSPublisher launch configuration is pre-selected in the Java Application section.
- Click the Run button in the Run dialog.
The JMSPublisher launch configuration executes the included JMSPublisher Java class, which, in turn, uses the default jms-publisher.sbconf configuration and messages.txt files to send messages to the default TIBCO JMS server.
Observe tuples displayed in the Application Output view after the publisher 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.
You may need to edit jmsreader.sbconf file to specify the site specifics of your JMS server. To do so, double-click the file in the Package Explorer. By default, the file includes configuration settings for TIBCO EMS.
Start the JMS server. For EMS, change directory to $TIBCO_HOME/ems/bin (%TIBCO_HOME%\ems\bin on Windows), and execute tibemsd.
Open several terminal windows on UNIX, or several 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.sbcoIn another window, tnf, 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, where jmsreader.jar is already referenced. An entry for the TIBCO EMS implementation file, tibjms.jar, is already included in sbd.sbconf.
Start StreamBase Server, using the -f option to reference the configuration file. For example:
```
sbd -f sbd.sbconf jms-sample.sbapp
```
From a terminal window, dequeue from one or more output streams. There are three output streams, MSFTOUT, STBSOUT, and ORACOUT. To dequeue from one or more of these, enter an sbc command like the following example, each in its own terminal window:
```
sbc dequeue MSFTOUT
```
Publish some messages to the JMS server. Follow Step 8 in the previous section to run the provided JMS publisher in StreamBase Studio.

As an alternative, open another terminal window and invoke the standalone publisher, sb-ems-publish. The publisher takes two arguments: a configuration file and a messages file. Both files, jms-publisher.sbconf and messages.txt, can be found in the sample project directory.

Keep in mind that the publisher also needs to refer to one or more JMS implementation JARs. In the case of EMS, this JAR is $TIBCO_HOME/ems/clients/java/tibjms.jar, or %TIBCO_HOME%\ems\clients\java\tibjms.jar on Windows.

On Linux, the CLASSPATH for this JAR file can be passed to the publisher on the command line. In the case of Windows, however, the .ini file for the publisher must be edited. In the file streambase-install-dir\bin\sb-ems-publish.ini, alter the Classpath entry to include any JMS implementation JAR files.

The commands to invoke the publisher will then look something like this:
Windows example:
```
sb-ems-publish .\jms-publisher.sbconf .\messages.txt
```
Linux example:
```
sb-ems-publish -c $TIBCO_HOME/ems/clients/java/tibjms.jar \
  ./jms-publisher.sbconf ./messages.txt
```
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