JMS and TIBCO EMS Configuration Editor

StreamBase Studio includes the JMS Configuration Editor, which provides a forms-based method for editing the server connection and destination specifications for one or more JMS or TIBCO EMS message servers. Starting with TIBCO StreamBase® release 7.5.4, the JMS Configuration Editor supports the JMS or TIBCO EMS operators introduced in that release. In particular, the JMS Configuration Editor now stores all JMS configuration information in the current Studio project's server configuration file, and no longer in separate .jmsconf files.

The JMS and TIBCO EMS Adapter is implemented as a suite of five operators for JMS and five for TIBCO EMS, as shown in the following table:

Each server connection specification is saved with a per-project unique connection name, and each JMS destination has a unique name per configured server. When using one of the JMS or TIBCO EMS operators, you specify a configured server and destination name, and the operator does the work of making and maintaining the connection to the specified server.

Starting with TIBCO StreamBase 7.5.4, the specifications for connecting to JMS and TIBCO EMS message servers are stored in an <adapter-configuration> element in the current project's primary server configuration file, usually named sbd.sbconf. As always, you are free to directly edit the XML of the sbconf file. However, Studio provides the JMS Configuration Editor described on this page as an easy-to-use forms-based method of editing JMS and TIBCO EMS specifications.

In releases before 7.5.4, JMS and TIBCO EMS configuration was specified in separate XML files with the .jmsconf extension that were independent of the project's server configuration files. The current JMS Configuration Editor can no longer be used to create new .jmsconf files or save in the .jmsconf format, but it can open such files and convert their server and destination specifications into the new <adapter-configuration> format. See Using Legacy Configurations.

To open the JMS Configuration Editor for the current Studio project, use steps like the following:

The default placement of the JMS Configuration Editor view is as a new tab in the same mid-central window where EventFlow canvases appear.

Because the JMS Configuration Editor edits the current project's sbd.sbconf file, it is possible for more than one editor to have the same .sbconf file open at the same time, which can lead to confusing and conflicting editing situations. For the utmost editing clarity, follow the rules and best practices in this section when using the JMS Configuration Editor:

Use the Server/Destinations tab to define connection configurations for JMS and TIBCO EMS servers, and to configure destinations for defined servers. This tab takes on a different look, depending on what it is currently editing:

Moreover, the set of available server configuration fields adapts to whether you select Direct or JNDI as the server connection type in the Connection Type quadrant in the upper right.

If you open the JMS Configuration Editor in a project with no previous JMS or EMS configuration in the current Studio project, then the Servers and Destinations control is blank. Click the green plus sign () to create a new server definition; this creates a server with the default name Server, which has one destination with the default name Destination. Each defined server must have at least one defined destination.

To rename a newly added server configuration, select the default name and enter a new name in the Name field of the Server Overview section. To rename the destination, select the default name and enter a new name in the Name field of the Destination Overview section.

See Minimum Configuration Requirements below for a discussion of the few server configuration settings you must specify to allow a successful connection.

The JMS Configuration Editor has two tabs selectable along its bottom edge. The primary Server/Destinations tab is described in other sections of this page.

The Timestamp Format tab has the single purpose of gathering timestamp format definitions for use in the Server/Destinations tab as part of the configuration of destinations.

A field, property, or header in a JMS or EMS message might represent a timestamp as a string such as yyyy-MM-dd. Use this tab to specify the format of that string, and provide a name for that format. Your named formats then appear in the Timestamp Format drop-down list in the Destination Overview section of each destination's configuration.

Define your time formats using the format characters recognized by the java.text.SimpleDateFormat standard.

If you do not specify any custom timestamp format strings in this tab, the Timestamp Format drop-down list in the destination configuration section contains the single format “DefaultTimestampFormat”. This default format string is:

MM/dd/yyyy hh:mm:ss aa

The Server/Destinations tab allows for maximum flexibility in configuring JMS server and destination definitions, and allows for many special-case settings. At first glance, the number of fields in this tab can appear daunting. However, to make a successful connection to a JMS or TIBCO EMS message server requires only a few settings.

The particular minimum settings required depend on the JMS Provider you are using. The JMS Operators have native support for four JMS Providers:

The required settings for these four JMS providers are shown in Configuration Settings Examples on the Authoring Guide's JMS Operators page.

See Connection Type Section, JNDI and Connection Type, Direct below for examples and explanations of the fields you must configure in the Connection Type section to allow a simple JMS or EMS connection to proceed.

For a successful connection, you also need the JAR files that implement JMS client functionality for your JMS Provider, as listed in JAR File Requirements. These JAR files must either be listed in the current Studio project's Java Build Path, or in the <java-vm> section of the project's sbd.sbconf file, or both.

When the minimum configuration settings are in place, test your connection by selecting your server's name in the Servers and Destinations control, and clicking the Test Connection button. This results in a dialog that reports either the success or failure of the connection attempt.

Both the JMS Configuration Editor and the underlying <adapter-configurations> element in sbd.sbconf support the configuration of more than one JMS and/or EMS servers, and you can easily mix configurations for different JMS Providers:

In the underlying XML, each server's configuration, along with all of its configured destinations, is kept in a separate <jms-server> child element:

<adapter-configurations>
  <adapter-configuration name="jms">
    <sb-jms-adapter-config 
      adapter-class="com.streambase.sb.adapter.jms2.JMSConsumer">
      <jms-servers>
        <jms-server name="EMS-81" provider-name="TIBCO EMS" 
          connection-factory-name="ConnectionFactory" 
          provider-context-factory="com.tibco.tibjms.naming...
          ...
          <destinations>
            <destination is-topic="false" name="queue.SimpleSampleQueue"/>
            <destination is-topic="false" name="queue.TextMessageQueue2"/>
          </destinations>
        </jms-server>
        <jms-server name="Lab-ActiveMQ" provider-name="Apache ActiveMQ"
          connection-factory-class="org.apache.activemq...
          ...
          <destinations>
            <destination name="queue.SimpleSampleQueue"/>
          </destinations>
        </jms-server>
      </jms-servers>
    </sb-jms-adapter-config>
  </adapter-configuration>
</adapter-configurations>

As illustrated in this XML excerpt, there is no conflict between JMS servers from different JMS Providers. However, you must configure each server's configuration one at a time, independent of each other, following the best practice rules in Best Practices and Cautions above.

The JMS and EMS Input Adapter and Output Adapter from StreamBase release 7.5.3 and earlier are still present but deprecated in release 7.5.4 and later. Your StreamBase applications that use these adapters still compile and run under current StreamBase Server releases.

If you must maintain an application that uses the older JMS or EMS Adapters, then keep an installed copy of TIBCO StreamBase 7.5.3 or earlier. You can use the previous version of the JMS Configuration Editor from the older release to continue maintaining your .jmsconf files until you are ready to upgrade.

However, as noted above, the JMS Configuration Editor included with TIBCO StreamBase 7.5.4 and later does not save configurations in the .jmsconf file format. TIBCO strongly recommends upgrading your applications to take advantage of the features of the new JMS operator suite in place of the Adapters provided in earlier releases.

You can easily migrate the server and destination configurations from an existing project's .jmsconf file. To do so:

The import always preserves the server name specified in the .jmsconf file. This means:

The following features of the older JMS Configuration Editor from StreamBase release 7.5.3 and earlier have no corresponding feature in the Editor of release 7.5.4 and later:

*However, the Timestamp Formats section of the old Field Maps tab is preserved in the Timestamp Formats tab of the new Editor.

Each server and each destination within it must have a unique name per Studio project folder. When you add a new server in the Servers and Destinations section of the Servers/Destinations view, provide a name for it in the Server Overview section.

Use the tool bar at the upper right to add and remove servers and destinations, and to test server connections:

Newly added servers must have a certain minimum set of configured fields for a test connection to that server to succeed. See Minimum Server Configuration Requirements.

Use the Server Overview section to specify a name and optional description for the selected server.

If you opened the JMS Configuration Editor from a JMS operator, the JMS Provider drop-down list shows the four supported JMS Providers, plus Other. Select the appropriate JMS Provider or select Other if you intend to define your own JMS Provider configuration.

Use the Destination Options section for the selected server to specify certain defaults for all destinations configured for this server. The following image shows the default selections for this section.

The following table describes the Destination Options settings of this section.

The minimum settings for a JNDI connection to TIBCO EMS and Apache ActiveMQ require only three settings for a JNDI type connection:

These minimum settings are made in the Connection Type section in the upper right quadrant of the Server/Destinations tab, when the JNDI connection type is selected.

Remember that a successful connection requires the JAR files that implement JMS client functionality for your JMS Provider, as listed in JAR File Requirements. These JAR files must either be listed in the current Studio project's Java Build Path, or in the <java-vm> section of the project's sbd.sbconf file, or both.

You can test your configuration's connection to its specified server as described in Minimum Server Configuration Requirements.

To specify a connection to a JMS or TIBCO EMS server using the Direct connection type, you must specify two fields:

Examples, first for a direct connection to TIBCO EMS:

For an Apache ActiveMQ direct connection:

Of course, direct connections have the same JAR file requirements listed in the previous section, and can be tested with the Test Connection button described in Minimum Server Configuration Requirements.

The Advanced JNDI Options are sometimes needed to establish the proper InitialContext for JNDI lookups. These fields have no default values. Contact your site's JMS Network Administrator for the correct values for your site.

The following table describes the fields of the Advanced JNDI Options section

The values of the Connection Options section are optional unless your JMS Provider requires authentication information such as a user name and password.

The following table describes the Connection Options properties, which are all string values.

A destination is a queue or a topic on a particular server.

Select a destination name in the Server and Destinations control, which puts the JMS Configuration Editor into its destination editing mode.

Use the Destination Overview section to specify a name for the selected destination, and its Destination Type, either Topic or Queue.

Use the Custom Converter Settings field to enter an arbitrary string that is to be passed verbatim to the message converter specified in the Consumer Options or Producer Options section. Remember that the string you specify here will be stored in an XML element in the sbd.sbconf file. You must therefore escape characters that could be interpreted as part of the enclosing XML, such as < and >. Escape such characters with double quotes, or by substituting a character entity.

The Timestamp Format control is a drop-down list that by default has a single entry, defaultTimestampFormat. This default format string is defined internally as MM/dd/yyyy hh:mm:ss aa. To add your own timestamp format entries to this drop-down list, use the Timestamp Formats tab as described in Timestamp Formats Tab above.

The options in the Consumer Options section apply when the currently selected destination is used by a JMS Consumer or EMS Consumer operator.

The following table describes the Consumer Options section of each destination's configuration.

The options in the Producer Options section apply when the currently selected destination is used by a JMS Producer or EMS Producer operator.

The following table describes the Producer Options section of each destination's configuration.