Configuring Connection Details

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

SolacePubSub+ Connection Details

The Spring Cloud Stream Binder for PubSub+ uses Spring Boot Auto-Configuration for the Solace Java API to configure its session. In the application.yml, this typically is configured as follows:

solace:
  java:
    host: tcp://localhost:55555
    msg-vpn: default
    client-username: default
    client-password: default

For more information and options to configure the PubSub+ session, see Spring Boot Auto-Configuration for the Solace Java API.

Preventing Message Loss when Publishing to Topic-to-Queue Mappings

If the connector is publishing to a topic that is subscribed to by a queue, messages may be lost if they are rejected (for example, if queue ingress is shut down).

To prevent message loss, configure the reject-msg-to-sender-on-discard option with the including-when-shutdown flag.

TIBCO EMS Connection Details

Manual Configuration

To manually configure TIBCO EMS connection details, set the following in application.yml:

solace: 
  tibco-ems:
    server-url: tcp://localhost:7222 
    username: username
    password: password 
    properties: 
      <key>:<value>

Properties are key/value pairs where key starts with the com.tibco.tibjms.* prefix. These properties are passed without validation as a Mapto the TIBCO EMS JMS Connection Factory. Accepted properties can be found in Tibjms and in TibjmsSSL.

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 TIBCO EMS server as the JNDI provider could look like:

jms-binder: 
  jndi: 
    context:
      java.naming.factory.initial: com.tibco.tibjms.naming.TibjmsInitialContextFactory 
      java.naming.provider.url: tibjmsnaming://localhost:7222

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 broker.
<somePassword> is the password to authenticate with the JMS broker.

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

JMS Binder Configuration Options

The following properties are available at the binder level.

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 JMS binder transitions from `RECONNECTING` to `DOWN`. A value of 0 means an unlimited number of attempts which means that the binder never transitions to the `DOWN` state.
`healthcheck.reconnectattempts-until-down`	`long`	>= 0	10	The number of reconnection attempts until 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 section for details.
`jndi.connectionfactory.name`	`String`			The connection factory's JNDI name used for the lookup
`jndi.connectionfactory.user`	`String`			The user to authenticate with TIBCO EMS.
`jndi.connectionfactory.password`	`String`			The password to authenticate with the TIBCO EMS.

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 a 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