Configuring connections to messaging brokers

This topic describes the configuration of connections to a messaging broker.

Overview

Broker connection configurations describe the connectivity information required to allow connections to be established to a broker from an IBM® WebSphere® sMash application. Broker connection configurations are used by various components of the IBM Reliable Transport Extension.

There are two main configuration concepts:

Broker connection configurations: A broker connection configuration describes the connection information for a single broker.
Home broker configuration: The home broker configuration nominates an individual broker connection configuration that represents the home broker for the application. An application can have at most one home broker.

Broker connection configuration

Configuration of each broker connection is made in zero.config under the key /config/connection/messaging/ brokerName. For example, the following stanza describes a broker connection named myBroker:

/config/connection/messaging/myBroker = {
  "hostname" : "localhost",
  "port" : 9091
}

It is suggested that the broker connection name used for the key /config/connection/messaging/ brokerName matches the name of the remote broker to which the connection will be established; that is the name set as /config/messaging/broker/name in the remote broker configuration. The broker name can contain up to 20 characters.

The properties of a broker connection configuration are as follows:

Property	Description	Default
`localhost`	Remote broker host name.	Required.
`port`	Remote broker port number.	Required.
`trustStore`	File name of trust store to be used to validate server identity. Required if remote broker is using a secure connection.	None set.
`trustStorePassword`	Trust store password. (XOR strings are supported)	None set.
`trustStoreType`	Trust store type.	None set.
`connectionsPooled`	Set to `false` to turn off broker connection pooling.	`true`
`poolSize`	Maximum number of broker connections that may be held by the pool.	`20`
`poolExpiryTime`	Expiry time for pooled connections, in milliseconds.	`10000`
`deliveryTimeout`	The length of time that the client should wait for the broker to acknowledge requests, in milliseconds. If acknowledgments are not received within this time interval, the application will receive an exception.	`60000`

See Configuring a messaging broker for more information about SSL configuration and valid key store and trust store type values.

Connection pooling

By default, the IBM Reliable Transport Extension manages a pool of connections to the remote broker. When the application needs one, the pool is examined for a suitable connection and, if one is found, a pooled connection is allocated to the application. When the application has successfully finished with a connection, it is returned to the pool for potential reuse.

Pooling connections reduces the overheads associated with opening and closing connections to the broker for each individual request. A side effect of pooling is that idle connections may be held open by the application for longer than is necessary to complete a request.

To disable connection pooling for an given broker connection, set connectionsPooled to false.

A pooled connection will not be reused if it lies idle for longer than the period specified by poolExpiryTime. The maximum number of unallocated connections that may be held in a pool is specified by poolSize. If this maximum size is reached, the oldest connection in the pool will be closed.

Bridge connection configuration

A bridge connection configuration is a broker connection configuration that is used by a messaging broker that needs to establish a store-and-forward bridge to another broker. As with other broker connection configurations, a bridge connection configuration is made under /config/connection/messaging/ but it can have some additional properties.

For example, the following stanza describes a bridge connection named myBroker:

/config/connection/messaging/myBroker = {
  "hostname" : "localhost",
  "port" : 9091,
  "bridgeCredentials" : {
    "userid" : "user1",
    "password" : "pass1"
  },
  "bridgeState" : "normal"
}

The optional bridgeCredentials map contains the userid or password to use to establish a store-and-forward bridge to another broker. XOR strings are supported for the password value. The bridgeCredentials map should not be specified if the remote broker is not secured.

To establish the bridge, the user ID and password must be authenticated by the remote broker. The user ID must be authorized to send messages to the target queues identified for store-and-forward processing.

The optional bridgeState parameter controls how the bridge connection manager will treat this bridge connection:

normal: This bridge connection can be used for store-and-forward processing. The bridge connection manager will attempt to establish connections and flow messages for any corresponding store-and-forward queues. This is the default value.
quiesced: This bridge connection is out of service. The bridge connection manager will suspend store-and-forward processing using this connection and disconnect when in flight messages have been processed. The bridge connection can be put back into service at a later date, by setting bridgeState back to normal.

See Store-and-forward processing in multiple messaging broker topologies for more information about store-and-forward processing.

Home broker configuration

A home broker configuration is required by some messaging functionality, such as store-and-forward processing. A home broker configuration simply nominates an individual broker connection configuration as the home broker connection.

For example, the following configuration specifies that the myBroker configuration is the home broker configuration for this application:

/config/messaging/client/homeBroker = "myBroker"