Configuring 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 the queue ingress is shutdown.

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

Configuring Connection Details

Manual Configuration

To manually configure IBM MQ connection details, set the following in application.yml:

ibm:
  mq:
    user: admin
    password: passw0rd
    channel: DEV.APP.SVRCONN
    queue-manager: QM1
    conn-name: localhost(1414)
    additional-properties:
      <key>: <value>

Additional properties are key-value pairs where key can either be the real string for the property, which often starts with XMSC, or the variable as known in the WMQConstants class.

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 the File System JNDI service provider could look like:

jms-binder: 
  jndi:
    context:
      java.naming.factory.initial: com.sun.jndi.fscontext.RefFSContextFactory
      java.naming.provider.url: file:/path/to/bindings/file

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.

If the connector is running as a container and testing with the File System JNDI service provider, consider mounting the .bindings file with a docker bind mount and then setting java.naming.provider.url to the target of that mount.

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.

Secure Connections

For versions 2.3.0 and later of this connector, you can create an SSLBundle to configure a secure connection to IBM MQ, and then reference that SSLBundle using the ibm.mq.ssl-bundle property. For example:

spring:
  ssl:
    bundle:
      jks:
        my-bundle:
          truststore:
            location: "/path/to/truststore.jks"
            password: "changeit"
            type: "JKS"
ibm:
  mq:
    user: app
    password: passw0rd
    channel: DEV.APP.SVRCONN
    conn-name: localhost(1414)
    ssl-bundle: my-bundle
    additional-properties:
      WMQ_SSL_CIPHER_SUITE: TLS_RSA_WITH_AES_128_CBC_SHA256 # As an example

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