Contents
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.
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.
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.
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.
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.
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.
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 copytopics.sample.conf
to a location where your JMS server can find it. For EMS, this location is
, 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.%TIBCO_HOME%
\ems\bin\topics.conf -
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
on Windows), and execute tibemsd.%TIBCO_HOME%
\ems\bin -
You may need to edit
jmsreader.jmsconf
andjmswriter.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, specifyjmsreader.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 thetoolbar 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, selectmessagesToSendToJMS.sbfs
and click the run button at the bottom left of the tab. This will cause the application to start sending tuples to theTuplesDestinedToJMS
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.
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 copytopics.sample.conf
to a location where the JMS server can find it. For EMS, this location is
, 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.%TIBCO_HOME%
\ems\bin\topics.conf -
Start the JMS server. For EMS, change directory to
($TIBCO_HOME
/ems/bin
on Windows), and execute tibemsd.%TIBCO_HOME%
\ems\bin -
You may need to edit
jmsreader.jmsconf
andjmswriter.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 thesbd.sbconf
file, in one or more<jar>
directives. An entry for the TIBCO EMS implementation file,tibjms.jar
, is already included insbd.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
andYHOO_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
In StreamBase Studio, import this sample with the following steps:
-
From Studio's top menu, select
→ . -
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.
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 default location of studio-workspace
on your system.