Usage Instructions

Please note that this software is still in Alpha form and that I take no responsibility whatsoever on it's performance or lack of it!

Message generating programs and message consuming programs need to connect to their nearest ZMessageQueue node to send and receive messages. This connection is made with XML-RPC.

Message generators need only to connect and publish messages to a topic.

A consumer must subscribe to a topic. Subscriptions are persistent, meaning that once a program has subscribed, all messages to that topic will be kept for it, until the program has retrieved and acknowledged the messages. A program must explicitly unsubscribe if it no longer wants messages of a certain topic. Note that a program subscribes to a topic on a specific node - if that program wants to connect to another node, it must subscribe to the same topic on the new node too. Consumers retrieves messages from the node, processes them and then acknowledges that the messages have been received. Only then will the node know that the next time the application asks for messages not to re-deliver the received messages to it. This ensures that even if the client application crashes, it's messages will be kept and re-delivered until it acknowledges receipt.

The old API for node object exposes five methods that can be used by external apps (clients):

publishMessageToTopic(topicId, message)
subcribeToTopic(topicId, applicationId)
unsubscribeFromTopic(topicId, applicationId)
readMessagesFromTopic(topicId, applicationId) -> returns a list of (messageId, message) tuples
ackMessagesFromTopic(topicId, applcationId, messageIds) (messageIds is a list of messageId)

The new API exposes three more methods that can be used by external apps (clients):

publishMessagesToTopic(topicId, messages)
getTopics()
removeTopic(topicId)

Publisher Actions

publishMessageToTopic(topicId, message) - message is a picklable, XML-RPC marshable object.

publishMessagesToTopic(topicId, messages) - messages is a list of messages (as above)

Subscriber Actions

getTopics() - get a list of available topic ids

subscribeToTopic(topicId, applicationId) - subscribe to a topic, the client application must give a id that is used by the system to keep messages for the application if it is offline.

removeTopic(topicId) - remove the topic from the current node (not on all the nodes!)

readMessagesFromTopic(topicId, applicationId)

process messages

ackMessagesFromTopic(topicId, applicationId, messageIdList) - acknowledge the receipt of a list of message ids received