Connecting Container Streams Through JMS

Contents

Prerequisites

To use JMS container connections:

  • Your StreamBase installation must have the optional JMS Adapter kit installed.

  • Your StreamBase license must allow you to use the JMS embedded adapters.

  • 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 Ways to Set Up 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 the StreamBase Server configuration file

  • In StreamBase Studio when setting up a launch configuration

  • 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 sbdest 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 Configuration Defaults. Then run: 

sbadmin -u sb://sbprime:9900 addContainer primeholder primary.sbapp \
   primeholder.Outgoing=jms:jndi:sbdest
sbadmin -u sb://sbsecond:9900 addContainer secondholder secondary.sbapp \
   jms:jndi:sbdest=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 an RFC working draft.

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 this 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:sbdest
?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 Configuration 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 Configuration Defaults

To avoid typing long JMS URIs, you can store defaults for your JMS connection in the StreamBase Server configuration file.

JMS Configuration Parameters for 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.

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" />
  ...
</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 for Only in Configuration File

The server configuration file also accepts default settings for your JMS configuration that do not have equivalent JMS URI query parameters. 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>

Documentation for this set of parameters can be found in the following file installed with the EMS/JMS adapter kit: 

streambase-install-dir/sample/adapter/embedded/jmsreader/skeleton.sbconf

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 EMS/JMS adapter kit can also optionally use adapter-specific configuration files with different names, and the same parameter names are used in both types of 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 EMS/JMS adapter itself.

If you need to make similarly-named settings for one of the EMS/JMS adapters, make that setting 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.

Related Topics

Back to top