Configuring connections to messaging brokers

Broker connection configurations describe the connectivity information required to allow connections to be established to a broker from an IBM® WebSphere® sMash application.

Overview

There are two main configuration concepts that are used to define connections to a messaging broker from an IBM WebSphere sMash application:

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 the zero.config file using the /config/connection/messaging/ brokerName key. For example, the following stanza describes a broker connection named myBroker:

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

The broker connection name used in the /config/connection/messaging/ brokerName key should match the name of the remote broker to which the connection is to 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 shown in the follow table:

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 can 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 receives 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 overhead associated with opening and closing connections to the broker for each individual request. A side effect of pooling is that idle connections can be held open by the application for longer than is necessary to complete a request.

To disable connection pooling for a given broker connection, set the connectionsPooled property to false.

  • A pooled connection is not be reused if it lies idle for longer than the period specified by the poolExpiryTime property.
  • The maximum number of unallocated connections that can be held in a pool is specified by the poolSize property. If this maximum size is reached, the oldest connection in the pool is 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 treats this bridge connection. The following options are available:

normal
This bridge connection can be used for store-and-forward processing. The bridge connection manager attempts 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 suspends 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 Considerations for store-and-forward scenarios 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"

Version 1.1.26825