Configuring a messaging broker

This topic describes how to create and start a messaging broker.

Overview

A messaging broker is a long running application that provides the messaging service to applications performing request processing. The following concepts need to be considered when creating a messaging broker:

Messaging broker: A named messaging broker runtime executing within a long running application.
Message store: A directory on the local filing system used by the messaging broker to persist messages.
Message service listener port: The port number on which the messaging broker will listen for connections from client applications. The messaging service listener can optionally use SSL encryption.
Message authorization rules: The authorization rules used by a secured messaging broker to determine whether to permit users access to messaging resources.

The long running messaging broker application must only contain the messaging broker and optionally a messaging kicker or other necessary product components. Application logic should reside in separate applications and communicate with the messaging broker via broker connections.

Broker configuration

To create a messaging broker, create a new application and include the zero.messaging.broker dependency. The following configuration is required in zero.config to start the messaging broker:

/config/messaging/broker/name: The unique name to be assigned to this broker. The broker name must be different from any other broker on the machine and from any other broker in your broker network. Once a broker has been started for the first time its name cannot be changed.
/config/messaging/broker/port: The port number on which the broker will listen for messaging connections. If the value is less than or equal to 0 the messaging broker will not be started.
/config/messaging/broker/messageStore: Specifies the directory on the local filing system in which the message store will reside. The message store will be created when the broker is started for the first time. Once created, the message store location cannot be changed. The default location is ${/app/root}/messageStore.

For example, the following configuration creates an unsecured broker, myBroker, to listen on port 9091:

/config/messaging/broker/name = "myBroker"
/config/messaging/broker/port = 9091
/config/messaging/broker/messageStore = "c:\zero\messageStore"

When a broker is created for the first time the message store is created and many of the configuration options cannot be changed. When configuring a broker for use in an application development environment it can be convenient to destroy the state of the broker from a previous test run and recreate it based on updated configuration. This can be achieved by setting /config/messaging/broker/destroyCurrentMessageStore to true. However, it is important to note that using destroyCurrentMessageStore will destroy any messages in the message store and so must not be used in production environments.

You may also wish to read Deployment notes and troubleshooting when deploying a messaging broker for the first time.

Advanced configuration

The following advanced configuration options may be used to specify the characteristics of the messaging broker and its message store. Most of these configurations options cannot be changed after the broker has been started for the first time. In many scenarios the default values will be sufficient and these configuration options need not be specified.

/config/messaging/broker/maxQueueDepth

The maximum number of undelivered messages that can be held be a queue. The default value is 32768. Cannot be modified after the message store has been created.

/config/messaging/broker/maxMessageSize

The maxumum size of an individual message that can be held on a queue, in kilobytes. If this value is increased, it may also be necessary to increase the transaction log size and delivery time out values for associated connections. The default value is 512. Cannot be modified after the message store has been created.

/config/messaging/broker/transactionLogSize

The size of the message store transaction log, in kilobytes. The default value is 20000. Cannot be modified after the message store has been created.

/config/messaging/broker/persistence

Message store persistence policy:

0 for no persistence. Messages will be held in memory and will be lost on shutdown.
1 for shutdown persistence. Messages will be only written to the message store during shutdown processing and so may be lost if the broker process is terminated abnormally.
2 for full persistence. Messages will be always written to the message store.

The default value is 2. Cannot be modified after the message store has been created.

/config/messaging/broker/bridgeRetryInterval

The interval between attempts to re-establish a store-and-forward bridge connection to a remote broker that is unavailable, in seconds. The default value is 30 seconds.

/config/messaging/broker/bridgeRetryDuration

The maximum length of time over which attempts to re-establish a store-and-forward bridge connection will be made, in minutes. The default value is 0 (retry forever).

/config/messaging/broker/bridgeIdleTimeout

The length of time the bridge connection manager will retain a flow for an idle store-and-forward queue, in minutes. If set to 0, the flows will not be expired. The default value is 60 minutes.

/config/messaging/broker/quiesceTimeout

The minimum period a quiesced broker will wait for active client sessions to complete their work before terminating their connections, in milliseconds. The default and minimum permitted value is 3000.

/config/messaging/broker/trace

The diagnostic trace level for the messaging broker. The default value is 1 (minimum trace).

Configuring a secured broker

In addition to the broker configuration described above, the following configuration is required for a secured broker:

A SSL configuration for the messages service listener port.
A user service configured for the long running broker application, against which messaging connections can be authenticated. See the "Developer's Guide" for more information.
Authentication rules for messaging resources, as described in Securing messaging resources

The SSL configuration for a message service listener port is specified using /config/messaging/broker/sslconfig, as in the following example:

/config/messaging/broker/sslconfig = {
   "keyStore" : "config/broker.jks",
   "keyStorePassword" : "123456",
   "keyStoreType" : "JKS"
}

The following properties are required:

Property	Description
`keyStore`	File name of key store containing the server certificate.
`keyStorePassword`	Key store password. (XOR strings are supported)
`keyStoreType`	Key store type.

The messaging broker uses the Java™ Secure Socket Extension (JSSE) implementation provided by the Java runtime environment. The supported key store and trust store type values are those supported by the underlying JSSE implementation. The most common key store types are JKS (Java Key Store) and PKCS12 (Personal Information Exchange Syntax Standard). See the SSL configuration documentation in the "Developer's Guide" for more information about valid key store and trust store types.