JMS and EMS Adapter Samples

About This Sample

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 provide setup your maven repository to include the required JMS jar files. The sample includes two launch files that can be used to install the required jar files to your local maven repository as an interim solution to try out the sample, however it is suggested that the required files be placed on a company wide maven repository. The jar files required are jms-2.0.jar and tibjms.jar or other applicable JMS implementation jar.

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

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

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

  • Click OK.

StreamBase Studio creates a single project containing the sample files.

Running The Samples in StreamBase Studio

A JMS implementation is not 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 your maven repository before the samples will properly run.

    Important

    Regardless of the JMS vendor used, you must also make sure your maven repository contains 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 Project Explorer, open the sample you just loaded.

  4. Open the src/main/eventflow folder.

  5. Open the package folder (most samples contain a single package folder. Open the top-level package folder if your sample contains more than one folder).

  6. Open the sbapp file corresponding to the sample application you wish to run.

    If you see red marks, wait a moment for the project in Studio to load its features.

    If red marks do not resolve themselves in a moment, select the project and right-click MavenUpdate Project from the context menu.

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

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

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

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

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

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

This Sample's Files

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 Consumer receives the JMS message 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.

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 permission problems. The default workspace location for this sample is:

studio-workspace/sample_adapter_embedded_jms

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