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.

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.

Configuring Connection Details

Manual Configuration

To manually configure Oracle AQ connection details, set the following in application.yml:

spring:
  datasource:
    url: jdbc:oracle:thin:@//localhost:1521/freepdb1
    username: username
    password: password

Connection properties can be specified as URL parameters or within a properties file.

To provide properties as URL parameters, use the EZConnect URL format.

To provide properties as a file, use the oracle.jdbc.config.file URL parameter to reference the file, for example:

url: jdbc:oracle:thin:@//localhost:1521/freepdb1?oracle.jdbc.config.file=file:///path/to/connection.properties

Refer to the documentation about Oracle connection properties files for information about the file format and other options.

JNDI

The JMS binder provides a generic way of configuring the connection details 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, such as java.naming.provider.url, and the value is a string in the format defined for that property.

For example, configuring access to an external LDAP JNDI service provider could look like:

jms-binder:
  jndi:
    context:
      java.naming.factory.initial: com.sun.jndi.ldap.LdapCtxFactory
      java.naming.provider.url: ldap://host:389
      java.naming.security.authentication: simple
      java.naming.security.principal: cn=db1aqadmin,cn=acme,cn=com
      java.naming.security.credentials: password

All classes required by the chosen JNDI service provider must be added to the classpath.

After the JNDI context has been successfully configured, Connection Factory Lookup, JMS Destination Types, or both 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 and are complementary to the properties in Configuring Connection Details.

The following 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 unlimited number of attempts which means that the binder would never transition 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 the Oracle AQ queue manager.
`jndi.connectionfactory.password`	`String`			The password to authenticate with the Oracle AQ queue manager.

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.
          # For instance, `environment.jms-binder.jndi.context` and `environment.jms-binder.jndi.connection-factory` configuration.

        # 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.

Note that each binder 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