Using the messaging kicker and receiver

Overview

The messaging kicker and receiver modules are used together to allow an application to start a new piece of request processing when a message arrives on a messaging queue.

Messaging kicker

The messaging kicker module typically runs in the long-running application that contains the messaging broker that owns the queue being watched. The messaging kicker periodically examines the queue and if a message is available sends an HTTP request to the application that hosts the corresponding messaging receiver.

Messaging receiver

The messaging receiver runs in another application. When the HTTP request is received from the messaging kicker, the messaging receiver reads a message from the queue and fires the message event to allow the message to be processed by an event handler.

The messaging kicker and messaging receiver reside in separate applications. The remainder of this topic describes how the messaging kicker and messaging receiver applications are configured.

Messaging kicker configuration

A messaging kicker can either be placed in the long-running application containing the messaging broker or in a separate application. When run in the same application as a messaging broker, the messaging kicker uses a local interface to determine whether there are messages on the queue. When run in a separate application, the messaging kicker establishes a remote connection to the home broker, for which it needs additional configuration.

The following configuration is required to use the messaging kicker:

• The application containing the messaging kicker must include the zero.messaging.kicker dependency.
• The application configuration must define one or more messaging kicker tasks.
• If the messaging kicker is being run remotely from the messaging broker, the application must include additional connection configuration.

Messaging kicker task configuration

The application configuration must contain one or more messaging kicker tasks. Each messaging kicker task monitors a single queue but an application can contain multiple kicker tasks, each monitoring different a queue.

The following example contains a messaging kicker task configuration:

/config/timer/tasks/myQueueKicker = { "delay" : 5 }

/config/handlers += [{
    "events" : "timer",
    "handler" : "zero.messaging.kicker.QueueKicker.class",
    "conditions" : "/event/_taskName =~ myQueueKicker",
    "instanceData": {
        "queueName" : "myQueue", 
        "receiverURL" : "http://localhost:8080/messaging/QueueReceiver"
        "config" : {
            # HTTP or HTTPS protocol configuration can be placed here
        }
    }
}]

Each messaging kicker has a unique timer task described by a /config/timer/tasks/ kickerName stanza. The delay value specifies the number of seconds that the timer task waits between the completion of one messaging kicker invocation and the start of the next.

The corresponding timer event handler describes the activity to be carried out by the messaging kicker task:

• The conditions clause identifies that this handler is to be used for the named messaging kicker task.
• queueName value identifies the queue to be monitored.
• receiverURL value identifies HTTP or HTTPS URL of the messaging receiver application.
• The optional config map can be used to specify the protocol configuration properties for the outbound HTTP or HTTPS connection to the receiver application. For more information about the HTTP and HTTPS protocol configuration parameters available, see the Developer's Guide reference on working with HTTP or HTTPS services using the Connection API.

It is important to ensure that the receiverURL specified identifies an individual messaging receiver in an individual application process.

Configuring a remote messaging kicker

A messaging kicker deployed in an application that does not contain a messaging broker requires configuration describing the connection to the broker.

The following example contains a remote connection configuration for a messaging kicker:

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

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

/config/messaging/client/kickerCredentials = {
    "userid" : "user1",
    "password" : "pass1"
}

The /config/messaging/client/homeBroker and /config/connection/messaging/ configName stanzas describe the home broker connection properties that the kicker uses to contact the broker owning the queue. A single home broker connection configuration is used by all kickers running in the application. See Configuring connections to messaging brokers for more information about the home broker configuration.

The /config/messaging/client/kickerCredentials stanza describes the user ID and password that the messaging kicker uses to connect to a secured broker. XOR strings are supported for the password value. A single kicker user ID is used by all kickers running in the application. The user ID must be given authority to read messages from all the queues being monitored. This stanza should not be specified if the broker is not secured.

Messaging receiver configuration

A messaging receiver resides in an application that includes the zero.messaging.receiver dependency.

An application containing a messaging receiver can process requests from multiple messaging kickers and hence messages from multiple queues. The message event handler definition is used to route incoming messages to the appropriate application logic. The application must include POST handler configuration for the messaging receiver, matching the receiverURL specified for the corresponding kicker.

The following example contains a messaging receiver configuration:

/config/handlers += [{
	"events" : "POST",
	"handler" : "zero.messaging.receiver.QueueReceiver.class",
	"conditions" : "/request/path =~ /messaging/QueueReceiver(/.*)?"
}]

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

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

/config/handlers += [{
  "events" : "message",
  "handler" : "myMessageHandler.groovy",
  "conditions" : "/request/messaging/queue =~ myQueue"
}]

/config/messaging/client/receiverCredentials = {
    "userid" : "user1",
    "password" : "pass1"
}

The following notes describe the stanzas in the above configuration:

• The POST handler configures a messaging receiver at contextRoot /messaging/QueueReceiver. It might be appropriate to also include an assoicated security rule to prevent unauthorized invocation of this receiver endpoint.
• The /config/messaging/client/homeBroker and /config/connection/messaging/ configName stanzas describe the home broker connection properties that the receiver uses to contact the broker owning the queue. The messaging receiver must use the same home broker as the corresponding messaging kicker.
• The message event handler describes the handler that is to be invoked when a message has arrived on the named queue.
• The /config/messaging/client/receiverCredentials stanza describes the user ID and password that the messaging receiver uses to connect to a secured broker. XOR strings are supported for the password value. A single receiver user ID is used by all message handlers in the application. The user ID must be given authority to read messages from the queue. This stanza should not be specified if the broker is not secured.

The conditions clause can be used to select a message event handler based on the name of the queue or criteria such as the message headers. It is important that the conditions clauses are written to ensure that any message that can arrive on the queue is matched by a message handler. If a message matches more than one conditions clause, it is processed by the first matching handler defined. If no matching message hander is registered, the receiver is unable to deliver the message and signals a failure to the messaging kicker. The message remains on the queue and the kicker continues to attempt to notify the receiver until the message has been delivered.

The message event

The message event is fired by the messaging receiver when a new message has arrived on a queue. The application logic required to process the message is implemented as a message event handler, in a similar way to a handler for an HTTP request.

When the message event is fired, the following values are available in the global context. These values can be used in the conditions clause to select a suitable event handler or to access the details of the message in the onMessage() implementation.

/request/messaging/kicker

The name of the message kicker.

/request/messaging/queue

The name of the queue on which the message arrived.

/request/messaging/message

The javax.jms.Message that has arrived.

/request/messaging/headers/ headerName

Message properties.