In This Section
Overview
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.
jms://<address>:<port>&prop1=val1&propN=valN
An example bus descriptor for using tibco ems
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
Decomposed
As A Descriptor
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:
Default to loopback for testing
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.
|
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 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
|
| 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 |
| 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.
| |
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". |
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 The minimum allowable value for retries in 250ms, specifying a lower value will cause it to be rounded up. |
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.
The ActiveMQ Binding
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
Decomposed
As A Descriptor
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 jms. The sections below utilize 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.
Sending Messages To Talon
The platform's JMS binding encodes a serialized message payload in a bytes message and sets metadata fields in its jms headers. The following example show
Receiving Messages from Talon
The following code sample shows how an external application using the JMS api directly can unpack a message sent over the platform's built in JMS binding and materialize it into a message view.