div

id	toc
class	toc

div

class	tocTitle

In This Section

div

class	tocContents

Table of Contents

maxLevel	2
indent	8px
style	none

Overview

Excerpt
The JMS binding works with JMS 1.1 level JMS clients and is configured using JNDI lookup. In addition to JNDI lookup the platform provides a subclassed version of the JMS binding optimized for working with ActiveMQ.

Bus Descriptor Format

A jms message bus can be configured via a descriptor string as follows which takes the connection information followed by a list of provider properties.

No Format
jms://<address>:<port>&prop1=val1&propN=valN

An example bus descriptor for using tibco ems

No Format

jms://tibcohost:2732&username=admin&password=changeme / 
&jndi=true / 
&jndi_contextfactory=com.tibco.tibjms.naming.TibjmsInitialContextFactory /
&jndi_principal=admin / 
&jndi_credentials=changme /
&jndi_connectionfactory=CSTopicConnectionFactory

DDL

In a DDL config file a jms bus can equivalently be configured in one two ways

Code Block

title	Decomposed

<buses>
  <bus name="my-bus">
    <provider>jms</provider>
    <address>192.168.1.9</address>
    <port>55555</port>
    <properties>
      <username>admin</username>
      <password>changeme</password>
      <jndi>true</jndi>
      <jndi_contextfactory>com.tibco.tibjms.naming.TibjmsInitialContextFactory</jndi_contextfactory>
      <jndi_principal>admin</jndi_principal>
      <jndi_credentials>changme</jndi_connectionfactory>
      <jndi_connectionfactory>CSTopicConnectionFactory</jndi_connectionfactory>
    </properties>
    <channels>
      ...
    </channels>
  </bus>
</buses>

Code Block

title	As A Descriptor

<buses>
  <bus name="my-bus" descriptor="jms://tibcohost:2732&username=admin&password=changeme / 
                                 &jndi=true / 
                                 &jndi_contextfactory=com.tibco.tibjms.naming.TibjmsInitialContextFactory /
                                 &jndi_principal=admin / 
                                 &jndi_credentials=changme /
                                 &jndi_connectionfactory=CSTopicConnectionFactory">
    <channels>
      ...
    </channels>
  </bus>
</buses>

Note the '/' denoting line breaks above would not be valid in actual XML – they are provided here for readability.

The descriptor form is useful in cases where the descriptor name may be supplied as an external configuration property that is substituted for example:

Code Block

title	Default to loopback for testing

<buses>
  <bus name="my-bus" descriptor="${myBusDescriptor::loopback://mybus">
    <channels>
      ...
    </channels>
  </bus>
</buses>

Generic JMS Binding Properties

The following properties can be set in the descriptor used to create a JMS bus binding.

Property Default Description

jndi

true

Indicates that JNDI should be used to lookup the connection factory for creating JMS connections.

When using jndi the address portion of the binding descriptor is used as the address at which to lookup the connection factory. The returned connection factory may connect to a different host.

jndi_contextfactory

-

The name of the environment property for specifying the initial context factory to use

jndi_principal

-

The name of the environment property for specifying the identity of the principal for authenticating the caller to the service

jndi_credentials

-

The environment property for specifying the credentials of the principal for authenticating the caller to the service

jndi_connectionfactory

-

The name of the connection factory to look up in jndi.

username

-

The username to supply in the credentials when opening the JMS connection

password - The password to supply in the credentials when opening the JMS connection

set_client_id

true

Specifies whether a client_id should be set for the connection.

When true Connection.setClientID(String) is set on the JMS connection. It is important that the client id be set when using Guaranteed Qos subscriptions as the durable subscriptions issued by the binding are tied to the ClientID.

When set to true, the client id X-SMA-<busname>-<bususer> will be used as the JMS ClientID unless "use_legacy_client_id" or "client_id" are set.

Note that the bususer value used in the ClientID is the username supplied during bus creation to identify the logical bus user not the username used in the credentials for connecting to the JMS broker.

If the JMS connection is created from a JNDI connection factory that provides a pre configured JMS ClientID it may cause the JMS provider to throw an exception when the client id is set. Consequently, this value should be set to false if the connection factory is supplying the client id.

Prior to the 3.8 release the ActiveMQ specific provider set a client of <username><busname>. The change to "X-SMA<busname>-<bususername>" is a breaking change in this case for applications that have existing durable subscriptions associated with the old Client ID. The property use_legacy_client_id=true can be set to use the old client id.

Status

colour	Green
title	Since 3.8

use_legacy_client_id

false

Specifies that the legacy client id should be used.

When set to true indicates that the default client of <bususer>-<busname> should be used rather than the default X-SMA-<busname>-<bususer>.

This property is ignored if "set_client_id" is false or "client_id" is used to set an explicit JMS ClientID. This property should only be set for applications that were using the activemq bus provider in 3.7 or earlier.

Status

colour	Green
title	Since 3.8

client_id

-

Can be used to specify a specific client id for the bus.

This property can be used to override the default client id when set_client_id is set to true.

Note that if the bus is shared between multiple applications, the client id should be different for each application, but the same for primary and backup instances.

Status

colour	Green
title	Since 3.8

connection_open_retry_count

10

Property controlling number of retries to attempt after a failure to open a connection.

When a connection attempt fails with a reason that isn't known to be a permanent condition, this property controls the number of reconnect attempt to try. Reconnect attempts will be attempted at the interval specified by "connection_open_retry_interval".

Status

colour	Green
title	Since 3.8

connection_open_retry_interval

1s

Property specifying the retry interval for connect open retries in seconds.

When no time unit suffix is provided for this value it is interpreted as the number of seconds between retries. Otherwise, a time suffix can be provided to qualify the unit as specified in UtlUnit.parseDuration(String, TimeUnit, TimeUnit).

The minimum allowable value for retries in 250ms, specifying a lower value will cause it to be rounded up.

Status

colour	Green
title	Since 3.8

JMS Topic Format

JMS Topics are JMS Provider specific. Currently the platform treats channel key levels as being delimited by a '/' and levels it up to the binding implementation to normalize topic levels to the level native to the JMS provider. For example the activemq and tibems providers both normalize the channel key separator to be '.' when sending or joining a channel.

Wildcard Topics

Support for topic wildcards is specifc to the JMS provider if supported at all. The generic JMS binding thus does not perform any special handling for wildcard characters and if nv.sma.cleanchannelfilter=true all non alphanumeric character are replaced with an '_' character (as they are for during message sends when nv.sma.cleanmessagekey=true.

The plaform's ActiveMQ and TibcoEMS specific binding implementations are sensitive to the following wildcards when nv.sma.cleanchannelfilter=true and will preserve these characters rather than replace them with an '_':

Wildcard

Description

*

Matches 0 or more characters within a topic level, and must be the only character in that level.

For example orders/*

would match sends to

orders/gin
orders/begin
orders/ginseng
orders/beginning

But not

orders
orders/in

...

Matches multiple topic levels and may only be used as the last level in a topic filter strings

For example orders/...

would match sends to

orders/events/MSFT
orders/updates/APPL
orders/cancels/US/IBM

But not

orders
order-updates

Sending and Receiving from External Applications

...

This section describes how to send to Talon applications from non Talon applications and from Talon application to non Talon applications over solacejms. The sections below utilize the ADM generated messages for convenience, but this is not required. For example, if you your messages are encoded in protobuf (or Xbuf) you could encode/decode the message yourself without using ADM. One such example of this might be if you were using C and generated protobuf message from the IDL generated by ADM.

...

Code Block

	java
	java

public void onMessage(javax.jms.Message message) {
  // extract sma metadata
  final boolean isMetadataPresent = message.getBooleanProperty(SMA_METADATA_PRESENT_JMSPROP);
  if (!isMetadataPresent) {
     // not an x message. 
     handleNonXMessage(message);
  }
  final byte encodingType = message.getByteProperty(SMA_METADATA_ENCODING_JMSPROP);
  final short vfid = message.getShortProperty(SMA_METADATA_VFID_JMSPROP);
  final short vtype = version > MessageMetadata.V1 ? message.getShortProperty(SMA_METADATA_VTYPE_JMSPROP) : 0;
 
  // extract payload
  Object payload = null;
  if(message instanceof TextMessage) {
     payload = ((TextMessage) message).getText(); 
  }
  else if(message instanceof BytesMessage) {
     payload = ((BytesMessage) message).getBytes(); 
  }
  else {
    handleNonXMessage(message);
    return;
  } 
 
  // lookup factory
  // (assumes that view factory have already been registered)
  MessageViewFactory factory = viewFactoryRegistry.getMessageViewFactory(vfid);
  if (factory != null) {
    MessageView view = factory.wrap(vtype, encodingType, payload);
    if(view instanceof OrderEventMessage) {
      handleOrderEvent((OrderEventMessage) message);
    }
  }
  else {
    handleNonXMessage(message);
    return;
  }
}

Provider Specific Implementations

ActiveMQ

While ActiveMQ can be configured via JNDI like any other JMS provider, the platform provides a custom 'activemq' bus provider.

The ActiveMQ binding is additionally optimized to:

Use ActiveMQ's INDIVIDUAL_ACKNOWLEDGE_MODE for channels using Guaranteed delivery.
Normalize subscribe and send calls to replace '/' delimited topics with '.' delimited topics which allows the same channel key configuration as other platform bindings.

DDL

In a DDL config file a activemq bus can equivalently be configured in one two ways

Code Block

title	Decomposed

<buses>
  <bus name="my-bus">
    <provider>activemq</provider>
    <address>192.168.1.9</address>
    <port>66666</port>
    <properties>
    </properties>
    <channels>
      ...
    </channels>
  </bus>
</buses>

Code Block

title	As A Descriptor

<buses>
  <bus name="my-bus" descriptor="activemq://192.168.1.9:66666"
    <channels>
      ...
    </channels>
  </bus>
</buses>

Tibco EMS

Status

colour	Green
title	Since 3.8

While Tibco EMS can be configured via JNDI like any other JMS provider, the platform provides a custom 'tibems' bus provider.

The Tibco EMS binding is additionally optimized to:

Use Tibco EMS' EXPLICIT_CLIENT_ACKNOWLEDGE for channels using Guaranteed delivery.
Normalize subscribe and send calls to replace '/' delimited topics with '.' delimited topics which allows the same channel key configuration as other platform bindings.

DDL

In a DDL config file a activemq bus can equivalently be configured in one two ways

Code Block

title	Decomposed

<buses>
  <bus name="my-bus">
    <provider>tibems</provider>
    <address>192.168.1.9</address>
    <port>7222</port>
    <properties>
    </properties>
    <channels>
      ...
    </channels>
  </bus>
</buses>

Code Block

title	As A Descriptor

<buses>
  <bus name="my-bus" descriptor="tibems://192.168.1.9:7222"
    <channels>
      ...
    </channels>
  </bus>
</buses>

The Talon Manual

Additional Links

Versions Compared

Old Version 2

New Version Current

Key

Overview

Bus Descriptor Format

DDL

Generic JMS Binding Properties

JMS Topic Format

Wildcard Topics

Sending and Receiving from External Applications

Provider Specific Implementations

ActiveMQ

DDL

Tibco EMS

DDL

The Talon Manual

Additional Links

Page History

Versions Compared

Old Version 2

New Version Current

Key

Overview

Bus Descriptor Format

DDL

Generic JMS Binding Properties

JMS Topic Format

Wildcard Topics

Sending and Receiving from External Applications

Provider Specific Implementations

ActiveMQ

DDL

Tibco EMS

DDL