Contents
This sample demonstrates the use of the Spotfire Streaming 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 Request/Reply operator to implement the request-reply design pattern, timing out after the configured amount of time if no reply is forthcoming.
-
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 in 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 a best practice 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.
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.
In StreamBase Studio, import this sample with the following steps:
-
From the top-level menu, select >.
-
Enter
jmsto narrow the list of options. -
Select JMS adapters and EMS adapters from the StreamBase Messaging Adapters category.
-
Click .
StreamBase Studio creates a single project containing the sample files.
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.
-
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 your Maven repository before the samples will properly run. See Using External JAR Files for instructions on installing JAR files.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 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. -
Optional. If you do not have an existing EMS or JMS server to connect to, you can run a local server. In this case, start the JMS server now. For EMS, navigate to
$TIBCO_HOME/ems/version/bin%TIBCO_HOME%\ems\version\bin -
In the Project Explorer view, open the sample you just loaded.
If you see red marks on a project folder, wait a moment for the project to load its features.
If the red marks do not resolve themselves after a minute, select the project, right-click, and select > from the context menu.
-
Open the
src/main/eventflow/folder.packageName -
Open the EventFlow module file corresponding to the sample you wish to run.
-
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 sample module is documented with self-describing comments. Hover over any of the components in the module for a description of what it does.
-
Make sure the module is the currently selected and active tab in the EventFlow Editor, then click the
button. This starts the application and switches to the SB Test/Debug perspective.
-
Use the Manual Input view in the top left of the SB Test/Debug view to send tuples to the available input streams.
-
Observe tuples displayed in the Output Streams view as the inputs are processed.
-
When done, press F9 or click the
Terminate EventFlow Fragment button.
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
commandfield contains either the stringconnectordisconnectto 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_ACKNOWLEDGEmode). 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.
- Request-Reply Sample 2 (
JMSRequestReplySample2.sbapp) -
This application demonstrates another way to implement the request-reply design pattern, using the JMS Request/Reply operator to send requests and wait for a configured period for the reply before timing out.
- 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
textfield. 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.
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_jmsSee Default Installation Directories for the default location of studio-workspace on your system.