Configuring Bus Connections

Message bus configuration is split between global (shared structure) and per-microservice (connection details) concerns.

Understanding Configuration Scope

Global Configuration defines the abstract bus structure shared across microservices:

• Bus names

• Channel catalog (channel names, QoS, key patterns)

Per-Microservice Configuration defines connection details specific to each microservice:

• Connection descriptors - Provider, address, credentials, and connection properties

Connection Descriptor Placement: While connection descriptors are conceptually per-microservice configuration, they are physically specified in the global <buses> section. This allows most descriptor properties to be shared while using substitution parameters to provide microservice-specific values (such as credentials or client IDs) in each microservice's configuration.

Global Bus Structure

The abstract bus structure is defined in the <buses>...</buses> section of the configuration DDL. This structure defines the bus name and the catalog of available channels.

Bus Properties

The following properties define the global bus structure:

Property	Required/Optional	Description
name	Required	The (unique) name of the bus. This name is used by microservices to reference the bus.
displayName	Optional, default=null	The (non-unique) display name of the bus.
enabled	Optional, default=true	Used to enable/disable the bus.
channels	Optional	The set of channels contained in the bus (the channel catalog). See below for channel properties.

Channel Properties

The following are the set of global bus channel properties.

Property	Required/Optional	Description
id	Optional, default=<not present>	The channel id. If present, it must be unique across all channels in the bus since it is used, in lieu of the channel name to uniquelt identify the channel in the bus system wide i.e., it is used, in lieu, of the name in the SMA metadata on the wire to identify the channel on which a message has travelled on the bus.
qos	Optional, default=Guaranteed	The channel quality of service. The value of this property must be either BestEffort or Guaranteed
key	Optional, default=null	The channel key

Connection Descriptor

The connection descriptor specifies how a microservice connects to the underlying messaging bus. Connection descriptors are conceptually per-microservice configuration - each microservice instance typically requires its own connection values (credentials, client IDs, provider-specific settings).

While physically specified in the global <buses> section, connection descriptors use substitution parameters to enable per-microservice values. The actual values are provided in the <xvm> section's <env> elements, allowing different microservice instances to connect with different credentials while sharing the same bus structure.

Descriptor Format

A connection descriptor can be specified in two forms:

Non-Decomposed Format

The descriptor can be specified as a single connection string using the format:

<provider>://<address>[:<port>][&prop1=value1][&prop2=value2]...

Example:

<bus name="sample-bus" descriptor="activemq://localhost:61616&set_key_on_receipt=true">
  <channels>
    <channel id="1" name="new-orders-channel">
      <qos>Guaranteed</qos>
      <key>NEWORDERS/${Region}/${Department}</key>
    </channel>
  </channels>
</bus>

Decomposed Format

Both formats support substitution parameters for per-microservice values:

<bus name="orders-bus">
  <provider>solace</provider>
  <address>${solace.host}</address>
  <port>${solace.port}</port>
  <properties>
    <username>${solace.username}</username>
    <password>${solace.password}</password>
  </properties>
</bus>

Provider-Agnostic Properties

The following connection properties are supported across all messaging providers:

Property	Default Value	Description
set_bus_and_channel_on_receipt	false	Controls whether the bus and channel name are set on received messages. Setting the channel and bus name on inbound messages incurs performance overhead. Performance sensitive applications should avoid enabling this property.
set_key_on_receipt	false	Controls whether the message key is set on received messages. Not all binding implementations transport the key on the wire, this property has no effect for bindings that don't transport the key. Setting the key on inbound messages incurs a performance overhead. Performance sensitive applications should avoid enabling this property.
set_sno_on_receipt	true	Controls whether the message sequence number is set on received messages. If set to false, then inbound messages surfaced to the AEP engine and application will not have the sequence number set regardless of whether the sender was configured to set sequence numbers in outbound messages or not. Setting the sequence number on inbound messages incurs a slight performance overhead. Performance sensitive applications should avoid enabling this property.
enable_inbound_transport_headers	false	Controls whether transport headers are set in inbound messages Setting this parameter to true will cause the bindings, that support this functionality, to set transport specific headers in the metadata section of the inbound messages Not all binding implementations support transport header functionality. This property has no effect for such bindings. Setting the sequence number on inbound messages incurs a performance overhead. Performance sensitive applications should avoid enabling this property. Additionally, enabling such a functionality fosters a tighter coupling between the application and specific message bindings which is generally not a recommended practice
topic_starts_with_channel	true	Controls whether topic names start with the channel name for the bus. For bus bindings that support topic routing this property controls whether or not the resolved key is prefixed with the channel name.
enable_concurrent_sends	false	Controls whether sends through the message bus binding can be performed concurrently using multiple threads
additional_properties_file	null	Specifies the path to an external file that is used to load additional bus configuration properties. The external file format is a plain java Properties file. Properties specified in the external file will be merged into configuration property set for the bus. This file is loaded at runtime, so the file is retrieved from the local file system on the host where the configured XVM will run.

Provider-Specific Properties

In addition to the provider-agnostic properties listed above, each messaging binding supports additional configuration properties specific to its underlying messaging technology.

For complete configuration reference and architectural information about each binding, see:

• Solace Binding - Configuration reference | Concepts

• JMS Binding - Configuration reference | Concepts

• Loopback Binding - Configuration reference | Concepts

• Executor Binding - Configuration reference | Concepts

Providing Per-Microservice Connection Values

Since connection descriptors are conceptually per-microservice configuration, each microservice typically needs to provide its own connection values (such as credentials, client IDs, or other provider-specific parameters). This is accomplished using substitution parameters in the global bus descriptor, with values provided in the <xvm> section where the microservice runs.

Example using substitution parameters:

<model>
  <!-- Global bus structure with parameterized connection descriptor -->
  <buses>
    <bus name="orders-bus">
      <provider>solace</provider>
      <address>${solace.host}</address>
      <port>${solace.port}</port>
      <properties>
        <vpn>${solace.vpn}</vpn>
        <username>${solace.username}</username>
        <password>${solace.password}</password>
      </properties>
      <channels>
        <channel name="new-orders">
          <qos>Guaranteed</qos>
          <key>ORDERS/${Region}</key>
        </channel>
      </channels>
    </bus>
  </buses>

  <!-- Application definitions (business logic) -->
  <apps>
    <app name="OrderProcessor" mainClass="com.example.OrderProcessor">
      <messaging>
        <bus name="orders-bus">
          <channels>
            <channel name="new-orders" join="true"/>
          </channels>
        </bus>
      </messaging>
    </app>

    <app name="InventoryService" mainClass="com.example.InventoryService">
      <messaging>
        <bus name="orders-bus">
          <channels>
            <channel name="new-orders" join="true"/>
          </channels>
        </bus>
      </messaging>
    </app>
  </apps>

  <!-- XVMs (containers) provide microservice-specific connection values -->
  <xvms>
    <xvm name="order-processor-1">
      <env>
        <solace.host>solace-prod.example.com</solace.host>
        <solace.port>55555</solace.port>
        <solace.vpn>prod-vpn</solace.vpn>
        <solace.username>order-processor-user</solace.username>
        <solace.password>${ORDER_PROCESSOR_PASSWORD}</solace.password>
      </env>
      <apps>
        <app name="OrderProcessor" autoStart="true"/>
      </apps>
    </xvm>

    <xvm name="inventory-service-1">
      <env>
        <solace.host>solace-prod.example.com</solace.host>
        <solace.port>55555</solace.port>
        <solace.vpn>prod-vpn</solace.vpn>
        <solace.username>inventory-service-user</solace.username>
        <solace.password>${INVENTORY_SERVICE_PASSWORD}</solace.password>
      </env>
      <apps>
        <app name="InventoryService" autoStart="true"/>
      </apps>
    </xvm>
  </xvms>
</model>

In this example:

• The global <buses> section defines the bus descriptor with substitution parameters like ${solace.username} and ${solace.password}

• The <apps> section defines the microservice business logic and which channels they join

• Each <xvm> (Talon container) provides its own connection values via <env> elements

• When an XVM starts, it resolves the substitution parameters using its <env> values, allowing each microservice instance to connect with different credentials

• This allows the abstract bus structure (channels, QoS, keys) to be shared while connection credentials remain microservice-specific