JMS and EMS Adapter Samples

Introduction

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.

JMS Server

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.

StreamBase Applications

This sample includes five different applications to demonstrate various tasks that can be performed by the adapter.

Simple EMS Sample (EMSSimpleSample.sbapp)

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.

Simple JMS Sample (JMSSimpleSample.sbapp)

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.

Manual Acknowledgement Sample (JMSAckSample.sbapp)

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.

Request-Reply Sample (JMSRequestReplySample.sbapp)

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.

Transacted Session Sample (JMSTransactedSessionSample.sbapp)

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.

Running The Samples in StreamBase Studio

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.

  1. The JMS implementation you use should provide one or more implementation JAR files, such as the tibjms.jar file 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 called jms-2.0.jar. Locate this file included in your JMS vendor's product installation alongside its other JAR files such as those mentioned above.

  2. Start the JMS server. For EMS, navigate to $TIBCO_HOME/ems/version_number/bin (%TIBCO_HOME%\ems\version_number\bin on Windows), and run tibemsd (tibemsd.bat on Windows).

  3. In the Package Explorer view, double-click on the .sbapp file corresponding to the sample application you wish to run to open the it in the EventFlow Editor.

  4. 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 Edit button to bring up the JMS Configuration Editor.

  5. 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.

  6. Make sure the 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.

  7. Use the Manual Input tab in the top left of the SB Test/Debug view to send tuples to the available input streams.

  8. Observe tuples displayed in the Application Output view as the inputs are processed.

  9. When done, press F9 or click the Stop Running Application button.

Importing This Sample into StreamBase Studio

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

  • From the top menu, select FileLoad StreamBase Sample.

  • Type jms to narrow the list of samples.

  • Select JMS/EMS Sample from the StreamBase Messaging Adapters list.

  • 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_jms

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/jms

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.