Contents
This sample demonstrates the use of the TIBCO StreamBase® Adapter for JMS and EMS, implemented as a suite of operators. The suite is composed of the following operators:
-
A JMS Consumer to read messages from a JMS server and send them to the StreamBase application as tuples.
-
A JMS Producer to send messages to JMS.
-
A JMS Connect operator to manually connect to and disconnect from the JMS server.
-
A JMS Ack operator to manually acknowledge incoming JMS messages.
-
A JMS Commit operator to commit or rollback transacted JMS sessions.
-
Also provided are five operators that are specific to the TIBCO EMS implementation of JMS, with the same functionality per operator: EMS Consumer, EMS Producer, EMS Connect, EMS Ack, and EMS Commit. The five EMS operators are TIBCO EMS-specific and do not run with any other JMS provider.
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 8.0 JAR file, when installed in its standard location.
You must also edit the JMS server configuration to provide site-specific information, such as the host name of your JMS server. As shipped, these files are configured for a TIBCO EMS server running on the default port of 7222 on localhost. Use the JMS Configuration Editor in StreamBase Studio to edit your server definitions.
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. However, the sample applications as shipped are configured to run against TIBCO EMS. To use these samples with your site's JMS implementation, you must reconfigure them.
The samples convey JMS messages to and from server over a JMS message bus. This means that at least one message bus must be
configured and running. In the included configuration files, one JMS server (named EMS-SERVER in the configuration) is referenced. This configuration may need to be changed to reference an actual JMS server at your
site.
This sample includes five different applications to demonstrate various tasks that can be performed by the adapter.
This is a trivial application that includes an EMS Producer that sends messages to an EMS Consumer. It also contains a simple way to manually disconnect from and reconnect to the EMS server using the EMS Connect operator.
When you send an empty tuple to the TriggerMsgSend input stream, the application constructs a tuple describing an EMS message and sends it to the server using the EMSProducer operator. The EMSConsumer operator receives the same message and sends it to the IncomingEMSMessage output port.
There is also a simple way to manually disconnect and reconnect to the EMS server by sending a tuple to the SendConnectCommand
input stream. Make sure the tuple's command field contains either the string connect or disconnect to get the desired result.
This is a trivial application that includes a JMS Producer that sends messages to a JMS Consumer. The functionality is the same as for the Simple EMS Sample described above, except that that sample is configured to use a non-TIBCO JMS implementation.
In this application, a JMS Producer feeds messages to a JMS Consumer that uses a manual acknowledgement mode (in this case,
TIBCO EMS' EXPLICIT_CLIENT_ACKNOWLEDGE mode). You can send JMS messages to the server by enqueuing an empty tuple to the TriggerJMSMsgSend input port. As this message
is then read by the Consumer, it is not acknowledged with the server until the appropriate tuple is sent to an instance of
the JMS Ack operator downstream.
This application demonstrates an end-to-end JMS request-reply scenario, where a request JMS message is sent with JMSReplyTo set to a different destination, and the reply is generated and sent back using the provided ReplyTo destination.
This application demonstrates the use of a JMS transacted session, where actions are not carried out unless and until the transaction is committed using the JMS Commit operator. If the transaction is rolled back instead, the actions that occurred during the transaction are dropped.
To see the sample in action, enqueue a tuple to the TriggerTextMsg input port, providing a value in the text field. The JMS message is received by the JMS Consumer in the transacted session, which triggers another message to be sent
to another destination via the JMS Producer operator using the same session. However, because this is a transacted session,
the message is not actually sent until the JMS Commit operator is invoked later downstream. Once it is sent, it is then read
back by another instance of the JMS Consumer and sent to the CommittedMsg output port.
A JMS implementation has not been included with the sample. In order to run the applications in 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.
-
The JMS implementation you use should provide one or more implementation JAR files, such as the
tibjms.jarfile provided by TIBCO EMS, 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 folder.Important
Regardless of the JMS vendor used, you must also provide a copy of
jms.jar. For TIBCO EMS, this file is calledjms-2.0.jar. Locate this file included in your JMS vendor's product installation alongside its other JAR files such as those mentioned above. -
Start the JMS server. For EMS, navigate to
$TIBCO_HOME/ems/version_number/bin%TIBCO_HOME%\ems\version_number\bin -
In the Package Explorer view, double-click on the
.sbappfile corresponding to the sample application you wish to run to open the it in the EventFlow Editor. -
You may need to edit the sample's JMS server definitions to specify the site specifics of your JMS server. To do so, select any of the JMS operators and click the button to bring up the JMS Configuration Editor.
-
Each application is thoroughly documented with self-describing comments. Just hover over any of the components in the application for a description of its function.
-
Make sure the application is the currently selected and active tab in the EventFlow Editor, then click the
toolbar button. This starts the application and switches to the SB Test/Debug perspective.
-
Use the Manual Input tab in the top left of the SB Test/Debug view to send tuples to the available input streams.
-
Observe tuples displayed in the Application Output view as the inputs are processed.
-
When done, press F9 or click the
Stop Running Application button.
In StreamBase Studio, import this sample with the following steps:
-
From the top menu, select → .
-
Type
jmsto narrow the list of samples. -
Select
JMS/EMS Samplefrom the StreamBase Messaging Adapters list. -
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_jmsSee 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/jmsSee Default Installation Directories for the default location of studio-workspace on your system.