Connecting Container Streams Through JMS

Prerequisites

To use JMS container connections:

Your StreamBase license must allow you to use the JMS embedded adapters unless you also have a TIBCO Enterprise Message Service™ server.
You must have a JMS server up and running.
You must specify the path to the JAR file that implements your JMS provider's functionality in your StreamBase Server configuration file. See Specify Path to JMS Provider's JAR File.

JMS Stream Connection Overview

You can connect two streams in containers on separate servers, with tuples passing through your site's Java Message Service (JMS) infrastructure. This feature allows you to use the reliable delivery feature of JMS to ensure delivery of StreamBase tuples. To use this feature, specify two container connections:

From StreamBase Server A to JMS.
From JMS to StreamBase Server B.

You can specify the two JMS connections in any of the ways you can specify container connections in general, as listed in Specifying Container Connections. That is, it is possible to specify JMS container connections:

On the command line with the sbadmin addContainer or sbadmin modifyContainer commands
In a StreamBase deployment file
In StreamBase Studio when setting up a launch configuration
In Studio in the Advanced tab of a stream's Properties view
Using StreamBase Manager

StreamBase supports JNDI-style JMS URIs, as described in Specifying JMS URIs.

Let's say we want to set up a JMS container connection that connects as follows:

From the output port Outgoing in the application primary.sbapp running in a container named primeholder on the StreamBase Server running on host sbprime.
To the JMS destination jmsdest on the JMS implementation running on the host and port specified in sbd.sbconf.
To the input port Incoming in the application secondary.sbapp running in a container named secondholder on the StreamBase Server running on host sbsecond.

First, start StreamBase Server on each host with no applications running. On both hosts, sbprime and sbsecond, run the same command:

sbd -f sbd.sbconf -p 9900

where sbd.sbconf specifies JMS configuration defaults as described in Specifying JMS Container Connection Defaults. Then run:

sbadmin -u sb://sbprime:9900 addContainer primeholder primary.sbapp \
   primeholder.Outgoing=jms:jndi:jmsdest
sbadmin -u sb://sbsecond:9900 addContainer secondholder secondary.sbapp \
   jms:jndi:jmsdest=secondholder.Incoming

The StreamBase applications do not run until the two sbadmin addContainer commands start the containers with their respective applications on each server. To establish the JMS container connection, the addContainer commands use the syntax for stream to stream container connections, but substitute a JMS endpoint for one side of each assignment.

Specifying JMS URIs

Specify JMS endpoints as a JMS URI. The format of a JMS URI is described in URI Scheme for Java Message Service.

StreamBase supports only JNDI-style JMS URIs, which, in their simplest form, look like the following example:

jms:jndi:destname

The JMS specification allows for multiple implementations called JMS providers. Each provider typically requires configuration information. For JMS container connections, this information can be specified in the endpoint JMS URI in the form of URI query parameters.

The following example of a full JMS URI has the following characteristics:

The URI shown below is one long line with no whitespace. It is shown broken into parts for readability.
The URI must begin with the string jms:jndi:
The next string after the second colon specifies the JMS destination, which is the specific JMS endpoint to which tuples are to be sent or from which retrieved. (Select the destination name as described in JMS Destination Names.)
The URI specifies three query parameters with values defined for each:
- jndiConnectionFactoryName
- jndiInitialContextFactory
- jndiURL
The values shown for the first two query parameters are specific for each JMS provider. The values shown in the following example are correct for using Apache ActiveMQ as the JMS provider.
The URI must use standard URI percent encoding for non-alphabetic characters such as colon (%3A) and slash (%2F).

jms:jndi:jmsdest
?jndiConnectionFactoryName=ConnectionFactory
&jndiInitialContextFactory=org.apache.activemq.jndi.ActiveMQInitialContextFactory
&jndiURL=tcp%3A%2F%2Flocalhost%3A9900

URIs of this length and complexity leave much room for error, if, for example, you had to type the entire URI twice in two sbadmin commands. For this reason, you can specify the defaults for the query parameters in the StreamBase Server configuration file, as described in Specifying JMS Container Connection Defaults.

JMS Destination Names

The name of the JMS destination to use in your JMS URI is site-specific. Determine the name of the appropriate destination as follows:

If you are using an existing JMS infrastructure, contact the administrator of the JMS server in use at your site.
If you are setting up a JMS service yourself for exclusive use in your StreamBase infrastructure, then you will name the destination yourself as part of that setup.

JMS destinations can be queues or topics, as discussed in Communication Style.

Specifying JMS Container Connection Defaults

To avoid typing long JMS URIs, you can store defaults for your JMS container connections in the StreamBase Server configuration file, using the <jms-connections-defaults> element.

Note

The <jms-connections-defaults> element of the server configuration file is used ONLY to specify JMS connection parameters for container connections over JMS. These settings do NOT manage or control the operation of the embedded StreamBase JMS adapters. Those adapters have their own independent configuration file formats described in Legacy JMS Input and Output Adapters.

JMS Configuration Parameters Specified in URI and Configuration File

The following table shows the parameters accepted as URI query parameters and the corresponding entry in the <jms-connections-defaults> element of the server configuration file.

JMS URI query parameter	StreamBase Server Configuration File Parameter
jndiConnectionFactoryName	connection-factory-name
jndiInitialContextFactory	provider-context-factory
jndiURL	provider-url
clientID	client-id
subscriberName	subscriber-name
deliveryMode	delivery-mode

Parameters specified in a JMS URI override the equivalent setting in the server configuration file, if any exists.

In addition to the parameters above, the following parameters can also be specified in the <jms-connections-defaults> element of the server configuration file:

server-num-retries -- in the event of a connection failure, this indicates the number of times a reconnection should be attempted. 0 means no attempt will be made; negative values are not allowed. The default value is 10.
server-reconnect-interval -- the number of seconds to wait between reconnection attempts. The default value is 5.

Use the server configuration file parameters as shown in this example:

<jms-connections-defaults>
  <param name="connection-factory-name" value="ConnectionFactory" />
  <param name="provider-context-factory" 
      value="org.apache.activemq.jndi.ActiveMQInitialContextFactory" />
  <param name="provider-url" value="tcp://localhost:9900" />
  <param name="client-id" value="site-specific" />
  <param name="subscriber-name" value="site-specific" />
  <param name="delivery-mode" value="site-specific" />
  <param name="server-num-retries" value="10" />
  <param name="server-reconnect-interval" value="30" />
  ...
</jms-connections-defaults>

The first three parameters are shown with example values for the Apache ActiveMQ JMS provider. The values for these parameters will be specific for your site and your JMS provider. The last three parameters are discussed in later sections on this page. The filler site-specific means to fill in a value appropriate for your JMS provider and site.

JMS Configuration Parameters Specified Only in Configuration File

There are JMS configuration settings that cannot be expressed as part of the JNDI-style JMS URI. These settings include security and login information such as username and password among other settings.

You must specify such settings using the <jms-connections-defaults> element of the server configuration file. The following example shows these settings, where the filler site-specific again means to fill in a value appropriate for your JMS provider and site:

<jms-connections-defaults>
  ...
  <param name="username" value="site-specific" />
  <param name="password" value="site-specific"/>
  <param name="acknowledge-mode" value="site-specific." />
  <param name="create-destinations" value="site-specific" />
  <param name="use-topics" value="site-specific" />
  <param name="jndi-security-principal" value="site-specific" />
  <param name="jndi-security-credentials" value="site-specific" />
  <param name="jndi-security-authentication" value="site-specific" />
  <param name="jndi-security-protocol" value="site-specific" />
  <param name="jndi-authoritative" value="site-specific" />
  <param name="jndi-dns-url" value="site-specific" />
  <param name="jndi-referral" value="site-specific" />
</jms-connections-defaults>

This group of parameters have the same names and meanings as parameters used by the JMS adapters. The documentation for this group of parameters is found in the skeleton JMS adapter configuration files installed with StreamBase in the following directory:

streambase-install-dir/sample/adapter/embedded/jmsreader/configurationFileReference

Server Configuration File Parameters Not Used by Adapter

The parameter settings described above are made in the StreamBase Server configuration file, usually named sbd.sbconf. The embedded and external JMS adapters can also optionally use adapter-specific configuration files with different names, and the same parameter names are used in both server and adapter configuration files.

However, any JMS configuration default parameters placed in the server's configuration file are interpreted only by StreamBase Server (sbd), and only for making JMS container connections. These settings in the server's sbd.sbconf file are not used in any way by the embedded or external JMS adapters.

If you need to make similarly-named settings for one of the JMS adapters, make those settings in one of the adapter's configuration files, not in the server's sbd.sbconf file.

Apache ActiveMQ Parameters

The JMS configuration settings in the examples on this page are the actual values required for a default setup of the Apache ActiveMQ JMS provider. Be sure to adjust all parameters for the JMS provider in use at your site.

Communication Style

JMS supports two communications styles: topics and queues. Queues are point-to-point connections between a single sender and a single receiver. Topics are a publish-subscribe mechanism, where there is one publisher and zero or more subscribers, each of which gets a copy of any published message.

By default, JMS container connections use the topics communication style. You can override this default by setting the use-topics parameter in the server's configuration file to false. In this case, JMS container connections use the queues method of communication.

Durability

Subscriptions can be set as durable or not. The subscriber determines the durability of the subscription at the time the subscription is made. If a durable subscriber goes down, messages published to the topic while the subscriber is down are saved and delivered to the subscriber when it comes back up. Durable subscriptions must specify both a client ID and a subscriber name property.

By default, JMS container connections use non-durable subscriptions. If you specify a subscriber name (in either the server configuration file or the JMS URI), you create a durable subscription. When you specify a subscriber name, you must also specify a client ID in the server configuration file or JMS URI. In practice, when using a subscriber name and client ID, specify them in JMS URIs, not the server configuration file. Otherwise, a single sbd instance can have only one durable container connection.

Messages have two related properties: delivery mode and time-to-live. Delivery mode can be persistent or non-persistent. For the Apache ActiveMQ JMS provider, to obtain the reliable delivery benefit of durable subscriptions, you must use persistent delivery mode. JMS container connections do not use the time-to-live value for messages.

The settings and defaults for your JMS provider may be different. Consult your JMS provider's documentation for details.

Specify Path to JMS Provider's JAR File

To use JMS container connections, each instance of StreamBase Server on either sending or receiving ends of the connection, must know where to load the functionality of the specific JMS provider. Use the <jar> element in the <java-vm> section of the server configuration file to specify the path to the JAR file that implements the JMS provider's functionality.

For example, the following server configuration setting configures StreamBase Server to use Apache ActiveMQ as the JMS provider:

<java-vm>
  <jar file="/path/to/activemq/installation/activemq-all-5.1.0.jar" />
</java-vm>

As always, paths in the server configuration file are either absolute or relative to the server's working directory.