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