> For the complete documentation index, see [llms.txt](https://docs.xplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xplatform.com/talon/developing-applications/configuring-messaging/configuring-bus-connections/jms-binding.md). # JMS Binding Configuration reference for the JMS message bus binding. ## Overview The JMS binding works with JMS 1.1 level JMS clients and is configured using JNDI lookup. The platform also provides provider-specific implementations optimized for ActiveMQ and Tibco EMS. For conceptual information about the JMS binding, see [JMS Binding](/talon/concepts-and-architecture/messaging-model/jms-binding.md). ## Bus Descriptor Format JMS buses can be configured using a descriptor string or decomposed DDL format. ### Descriptor String ``` jms://
:&prop1=val1&propN=valN ``` **Example** (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 ``` ### Decomposed DDL Format ```xml jms
192.168.1.9
55555 admin changeme true com.tibco.tibjms.naming.TibjmsInitialContextFactory admin changme CSTopicConnectionFactory ``` ### As Descriptor (Substitution Support) ```xml ``` The descriptor form is useful when the descriptor is supplied as an external configuration property: ```xml ``` ## 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-\-\ 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.



Breaking Change (3.8): Prior to the 3.8 release the ActiveMQ specific provider set a client id of \\. The change to X-SMA-\-\ is a breaking change 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.

| | `use_legacy_client_id` | false |

Specifies that the legacy client id should be used.

When set to true indicates that the default client id of \-\ should be used rather than the default X-SMA-\-\.

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.

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.



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 attempts to try. Reconnect attempts will be attempted at the interval specified by connection\_open\_retry\_interval.

Since 3.8

| | `connection_open_retry_interval` | 1s |

Property specifying the retry interval for connection 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 is 250ms, specifying a lower value will cause it to be rounded up.

Since 3.8

| ## 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 #### Decomposed DDL Format ```xml activemq
192.168.1.9
66666 ``` #### As Descriptor ```xml ``` #### Binding Specific Properties The ActiveMQ binding does not have any binding-specific properties beyond the [Generic JMS Binding Properties](#generic-jms-binding-properties) listed above. ### Tibco EMS **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 #### Decomposed DDL Format ```xml tibems
192.168.1.9
7222 ``` #### As Descriptor ```xml ``` #### Binding Specific Properties The Tibco EMS binding does not have any binding-specific properties beyond the [Generic JMS Binding Properties](#generic-jms-binding-properties) listed above. ## See Also * [JMS Binding](/talon/concepts-and-architecture/messaging-model/jms-binding.md) - Conceptual overview * [Configuring Bus Connections](/talon/developing-applications/configuring-messaging/configuring-bus-connections.md) - General bus configuration