Considerations for store-and-forward scenarios

Store-and-forward queue names

Store-and-forward queues are identified by a naming scheme. If a store-and-forward queue addresses queueName over the brokerName broker connection configuration then its name is as follows:

storeAndForward:brokerName/queue/queueName

The messaging protocol generates this name automatically when the storeAndForward property value is true. Therefore, applications using the Connection API do not need to specify the full store-and-forward queue name. However, the names of the store-and-forward queues do need to be considered in some circumstances, for example:

• The configuration of a secured broker configuration must provide authorization rules for the store-and-forward queues.
• An application using the broker statistics API is given details of the store-and-forward queues.
• An application using the external client API must to generate the appropriate queue names to use store-and-forward processing. The brokerName element is limited to 20 characters and the queueName element can contain up to 79 characters.

Store-and-forward synchronization queue

A special store-and-forward synchronization queue is used to store meta-data about the messages currently flowing from remote brokers that are using store-and-forward processing. It is automatically created when a broker receives an incoming store-and-forward connection.

The store-and-forward synchronization queue is called storeAndForwardSyncQueue. The configuration of a secured broker must provide authorization rules to permit incoming connections from remote brokers that are using store-and-forward processing to access the synchronization queue.

Store-and-forward bridge connections

To enable an application to use store-and-forward processing to send a message to a queue on a remote broker, its home broker requires a store-and-forward bridge connection configuration to allow it to contact the remote broker. A bridge connection configuration is specified in the same way as a broker connection configuration for an application but can have additional properties, such as the user credentials to use for the bridge connection.

For example, if a broker has a store-and-forward queue, storeAndForward:broker1/queue/queue1, it attempts to connect to a broker using the connection configuration, broker1 and forward messages to the remote queue, queue1.

Store-and-forward processing is not instantaneous. The time taken to deliver an individual message depends on several factors including the availability of the remote broker connection and the number of messages on the store-and-forward queue. When an application has placed a message on a store-and-forward queue, the following events must occur before it is delivered to the remote queue:

1. When a store-and-forward queue is first created, the bridge connection manager automatically starts a pipe to the remote broker and a flow to forward messages to the remote queue. This occurs within about a minute after the first message is placed on the queue.
2. When a pipe has been started, it attempts to connect to the remote broker. If the remote broker cannot be reached, then repeated attempts are made every few seconds.
3. When a pipe has been connected, the messages begin to flow from the store-and-forward queue to the remote queue. Message order is preserved, so the newest message on the queue waits for those placed on the queue before it to be delivered first.

After a pipe has been established, the bridge connection manager adds additional flows for store-and-forward queues to the same broker, as necessary. If the flow from a store-and-forward queue remains idle for a specified period of time, the bridge connection manager suspends it. When all the flows associated with a pipe are suspended, it is suspended too. A suspended flow or pipe is resumed when new messages arrive on the store-and-forward queue.

Authorization for store-and-forward processing

If secured broker is involved in a store-and-forward scenario additional considerations must be made when designing your authorization rules.

If the home broker of the sending application is secured then the user ID used by the sending application must be authenticated by the home broker and authorized to send messages to the store-and-forward queue. For example, if the application uses the identity "john" to send a message to queue "queue1" on "broker2" using store-and-forward processing, then a secured home broker might use the following authorization rule:

@include "security/messaging_rule.config" {
	"conditions" : "(/event/queue == storeAndForward:broker2/queue/queue1) && (/event/method == POST)",
	"users" : ["john"]
}

If the broker hosting the target queue is secured then the user ID used by the home broker to connect to the target broker (as specified in bridgeCredentials) must be authenticated by the target broker and authorized to send messages to the target queue. The user ID must also be authorized to send and receive messages from the storeAndForwardSyncQueue on the local broker. For example, if the home broker uses the identity "broker1" as its bridge credentials for "broker2" and has a store-and-forward queue to "queue1", then a secured target broker might use the following authorization rules:

@include "security/messaging_rule.config" {
	"conditions" : "(/event/queue == queue1) && (/event/method == POST)",
	"users" : ["broker1"]
}

@include "security/messaging_rule.config" {
	"conditions" : "(/event/queue == storeAndForwardSyncQueue)",
	"users" : ["broker1"]
}

Dynamic configuration for bridge connections

A messaging broker is a long running application that needs to remain active to provide messaging services to client applications. Changes to zero.config cannot be read and acted on without restarting the messaging broker and so potentially impacting client applications. However, it is possible to make changes to bridge connection configurations to allow store-and-forward processing to connect to new remote brokers without restarting the messaging broker.

To use the dynamic configuration mechanism, the bridge connection configurations must be placed in a separate configuration file. For example, if the bridge connection configurations are placed in the config/brokers.config file, then the following lines in zero.config enable dynamic configuration:

@include "brokers.config"
/config/messaging/broker/configFile = "config/brokers.config"

The bridge connection manager processes a dynamic configuration file as outlined in the following steps:

1. The last written time stamp of the dynamic configuration file specified by /config/messaging/broker/configFile is examined. If the time stamp has changed then dynamic configuration takes place:
   1. All running store-and-forward bridge connections are suspended.
   2. All messaging broker connection configurations stored under /config/connection/messaging are deleted.
   3. All messaging broker connections and connection pools are closed.
   4. The dynamic configuration file is read.
2. The bridge connection manager resumes normal processing and restarts the required bridge connections.

The following notes apply to the dynamic configuration mechanism:

• The dynamic configuration file is only supported in long running applications containing a running messaging broker.
• Dynamic configuration is only supported for messaging broker connections. The dynamic configuration file must only contain configuration keys of the form /config/connection/messaging/ brokerName.
• The dynamic configuration file can use the @include directive to reference additional files but included files are not be monitored for changes. The dynamic configuration is only loaded when the file specified by /config/messaging/broker/configFile has changed.