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 broker connection configuration brokerName then its name will be:

storeAndForward:brokerName/queue/queueName

The messaging protocol generates this name automatically when the storeAndForward property is true so applications using the Connection API do not need to be concerned with this naming scheme. 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 will need to provide authorization rules for the store-and-forward queues.
• An application using the broker statistics API will be given details of the store-and-forward queues.
• An application using the external client API will need 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 being flowed 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 will need to 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

If an application wishes to use store-and-forward processing to send a message to a queue on a remote broker, its home broker will require 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 will attempt to connect to a broker using the connection configuration, broker1 and forward messages to the remote queue, queue1.

It is important to note that store-and-forward processing is not instantaneous. The time taken to deliver an individual message will depend on several factors including the availability of the remote broker connection and the number of messages on the store-and-forward queue. Once an application has placed a message on a store-and-forward queue, a number of events must occur before it will be delivered to the remote queue:

1. After a store-and-forward queue is first created, the bridge connection manager will automatically start a "pipe" to the remote broker and a "flow" to forward messages to the remote queue. This will happen within about a minute after the first message is placed on the queue.
2. Once a pipe has been started, it will attempt to connect to the remote broker. If the remote broker cannot be reached, then repeated attempts will be made every few seconds.
3. Once a pipe has been connected, the messages will begin to flow from the store-and-forward queue to the remote queue. Message order is preserved so the youngest message on the queue will have to wait for those placed on the queue before it to be delivered first.

Once a pipe has been established, the bridge connection manager will start additional flows required by store-and-forward queues for the same broker. If the flow from a store-and-forward queue remains idle for a specified period of time, the bridge connection manager will suspend it. Once all the flows associated with a pipe are suspended, it too will be suspended. A suspended flow or pipe will be resumed after 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 sending application's home broker 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 which 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 file config/brokers.config then the following lines in zero.config will enable dynamic configuration:

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

The bridge connection manager processes a dynamic configuration file as follows:

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 will not be monitored for changes. The dynamic configuration will only be loaded when the file specified by /config/messaging/broker/configFile has changed.