Configuring Connection Details

This section provides instructions for configuring the connection details required to establish communication between the connector and your third-party system.

For information about configuring the connection to the event broker, see Connecting to Your Event Broker.

This connector supports workflows in the following directions:

Solace to JMS
JMS to Solace

The name of the binder for JMS is jms.

JMS Connection Details

Manual Configuration

The Connector for JMS does not support manual connection configuration as the JMS provider is not known in advance. In order to establish a connection with the JMS, it is essential to acquire a connection factory via a JNDI lookup. See JNDI for information on using JNDI.

JNDI

The JMS binder provides a generic way of configuring and using JNDI.

JNDI Context

The first step in using JNDI is to configure the JNDI context. The JMS binder expects standard JNDI properties to be specified under jms-binder.jndi.context in a key/value pair format. The key is the name of the property (e.g. "java.naming.provider.url") and the value is a string in the format defined for that property.

For instance, using the JMS server as the JNDI provider could look like:

jms-binder: 
  jndi: 
    context:
      java.naming.factory.initial: org.apache.activemq.jndi.ActiveMQInitialContextFactory 
      java.naming.provider.url: tcp://localhost:61616
      connectionFactoryNames: jndiConnectionFactoryName # ActiveMQ specific: the JNDI name the connection factory should appear as

Note that classes required by the chosen JNDI service provider need to be added to the classpath.

Once a JNDI context is successfully configured, connection factories and/or destinations can be looked up.

Connection Factory Lookup

To look up a connection factory, configure jms-binder.jndi.connection-factory.

jms-binder: 
  jndi:
    connection-factory:
      name: <jndiConnectionFactoryName>
      user: <someUser>
      password: <somePassword>

Where:

<jndiConnectionFactoryName> is the JNDI object name of the connection factory.
<someUser> is the user to authenticate with the JMS compliant broker.
<somePassword> is the password to authenticate with the JMS compliant broker.

The JNDI connection factories must not specify a clientID as this prevents producer bindings from connecting.

JMS Binder Configuration Options

These properties are to be prefixed with jms-binder.

Config Option	Type	Valid Values	Default Value	Description
`health-check.interval`	`long`	> 0	10000	Interval (in ms) between reconnection attempts while health status is `RECONNECTING`
`healthcheck.reconnectattempts-until-down`	`long`	>=0	10	The number of reconnection attempts until the JMS binder transitions from `RECONNECTING` to `DOWN`. A value of 0 means unlimited number of attempts which means that the binder would never transition to the `DOWN` state.
`jndi.context`	`java.util. Properties`	`key/value pairs`		Standard JNDI properties. See JNDI Context for more details.
`jndi.connectionfactory.name`	`String`			The connection factory's JNDI name used for the lookup
`jndi.connectionfactory.user`	`String`			The user to authenticate with the JMS compliant broker.
`jndi.connectionfactory.password`	`String`			The password to authenticate with the JMS compliant broker.

JMS Consumer Options

The following configuration options are available to JMS consumers. Options within the same table share the same prefix.

The following options in Config Option are prefixed with spring.cloud.stream.jms.bindings.<bindingName>.consumer.


Config Option	Type	Valid Values	Default Value	Description
`batch-max-size`	`int`	`>= 1`	`255`	The maximum number of messages that can be grouped together in a single batch. If a consumer polls for messages and none are available, a partial batch is created. You can configure the batch size to one to disable batching. It's important to note that all messages in the batch are rejected if both the following conditions exist: The `batchMaxSize` is more than 1. An error occurs during the processing of any message within the batch. For example, if you have a batch of 50 messages and one message fails, all 50 messages in the batch are rejected.
`transacted`	`boolean`	`true` or `false`	`true`	Specifies whether messages are received within a local transaction. When set to `true`, it indicates that the JMS consumer reads messages within a local transaction and commits the transaction when the batch has been successfully processed. Set to `false` to disable transactions. We recommend that you disable transactions because single message transactions (i.e., when `batch-max-size=1`) lower your performance significantly.
`destination-type`	`String`	`(queue \| topic \| unknown)`	`unknown`	The type of destination where messages are consumed from. queue The destination value is assumed to be a physical queue and no JNDI lookup is done. topic The destination value is assumed to be a physical topic and no JNDI lookup is done. This option requires `durable-subscription-name` to also be set. unknown The destination value is assumed to be a JNDI name. The actual destination name is only known after a successful lookup. A valid JNDI context must be configured via `jms-binder.jndi.context`.
`durablesubscription-name`	`String`	A valid subscription.	None.	The name of the shared durable subscription to consume from. The subscription is created on the broker if it doesn’t already exist. Applies, and is mandatory, when `destination-type` is or resolves to a topic.

The following options in Config Option are prefixed with spring.cloud.stream.bindings.<bindingName>.consumer.


Config Options	Type	Valid Values	Default Value	Description
`concurrency`	`int`	> 0	1	The number of concurrent consumers to create.

If a configuration option applies to all JMS input bindings, it can be prefixed with either:

spring.cloud.stream.jms.default.consumer if the option is from the first table.
spring.cloud.stream.default.consumer if the option is from the second table.

The mentioned classes are convenient way to assign a configuration to all JMS input bindings.

JMS Producer Options

The following configuration options are available to JMS producers.

The following options in Config Option are prefixed with spring.cloud.stream.jms.bindings.<bindingName>.producer.


Config Option	Type	Valid Values	Default Value	Description
`destination-type`	`String`	`(queue \| topic \| unknown)`	`unknown`	The type of destination where messages are published to. queue The destination value is assumed to be a physical queue and no JNDI lookup is done. topic The destination value is assumed to be a physical topic and no JNDI lookup is done. unknown The destination value is assumed to be a JNDI name. The actual destination name is only known after a successful lookup. A valid JNDI context must be configured via `jms-binder.jndi.context`.
`transacted`	`boolean`	`true` or `false`	`true`	Specifies whether the JMS producer publishes messages from a received batch using a local transaction. Setting transacted to `true` provides duplicate protection in case of producer failures. Set to `false` to disable transactions.

If a configuration option applies to all JMS output bindings, it can be prefixed with spring.cloud.stream.jms.default.producer. This prefix is a convenient way to assign a configuration to all JMS output bindings.

Connecting to Multiple Systems

To connect to multiple systems of the same type, use the multiple binder syntax.

For example:

spring: 
  cloud:
    stream: 
      binders:
        
        # 1st solace binder in this example 
     solace1:
          type: solace 
       environment: 
         solace: 
           java:
             host: tcp://localhost:55555
         
     # 2nd solace binder in this example 
     solace2:
          type: solace 
          environment: 
            solace: 
           java:
             host: tcp://other-host:55555
        
     # The only jms binder 
     jms1:
          type: jms
       # Add `environment` property map here if you need to customize this binder. 
       # But for this example, we'll assume that defaults are used.
          
     # Required for internal use 
     undefined:
          type: undefined 
     bindings:
          input-0:
            destination: <input-destination> 
         binder: jms1
          output-0:
            destination: <output-destination>
            binder: solace1 # Reference 1st solace binder 
       input-1:
            destination: <input-destination> 
         binder: jms1
          output-1:
            destination: <output-destination>
            binder: solace2 # Reference 2nd solace binder

The configuration above defines two binders of type solace and one binder of type jms, which are then referenced within the bindings.

Each binder above is configured independently under spring.cloud.stream.binders.<bindername>.environment..

When connecting to multiple systems, all binder configuration must be specified using the multiple binder syntax for all binders. For example, under the spring.cloud.stream.binders.<binder-name>.environment.
Do not use single-binder configuration (for example, solace.java.* at the root of your application.yml) while using the multiple binder syntax.

Provide feedback