From aaae850f5fbf931859cd444e3929c3a1a1fc6cfc Mon Sep 17 00:00:00 2001 From: kgriffs Date: Tue, 12 Aug 2014 18:06:12 -0500 Subject: [PATCH] Update use cases to align with dev guide and positioning This patch updates the language in the user guide to be more consistent with our current positioning of Zaqar, and to clarify some confusion around individual use cases. Change-Id: I32d75b3d4bec6ad758ef27fc3b5daf32651b1a44 --- .../zaqar-api-ref/os-zaqar-apiRef.xml | 71 +++++-- .../os-zaqar-apiGettingStarted.xml | 186 ++++++++++-------- 2 files changed, 158 insertions(+), 99 deletions(-) diff --git a/doc/user-guide/zaqar-api-ref/os-zaqar-apiRef.xml b/doc/user-guide/zaqar-api-ref/os-zaqar-apiRef.xml index 79cae5589..3c41ba629 100644 --- a/doc/user-guide/zaqar-api-ref/os-zaqar-apiRef.xml +++ b/doc/user-guide/zaqar-api-ref/os-zaqar-apiRef.xml @@ -133,15 +133,18 @@ following: - producer-consumer + Task distribution - publish-subscribe + Event broadcasting + + + Point-to-point messaging -
- Producer-Consumer - The producer-consumer pattern has the following +
+ Task distribution + The task distribution pattern has the following characteristics: @@ -169,27 +172,24 @@ This pattern is ideal for dispatching jobs to multiple processors.
-
- Publish-Subscribe - Characteristics of the Publish-Subscribe pattern +
+ Event broadcasting + Characteristics of the event broadcasting pattern are: - The publisher sends a message to a queue. + The publisher sends messages to a queue. - All workers (or subscribers) listen to the messages + Multiple observers get the messages in the queue. - Workers do not claim a message. - - - Multiple workers can take action on a + Multiple observers take action on each message. - Workers can send a marker or cursor to skip messages + Observers send a marker to skip messages already seen. @@ -197,7 +197,38 @@ This pattern is ideal for notification of events to - multiple workers at once. + multiple observers at once. +
+
+ Point-to-point messaging + Characteristics of the point-to-point messaging pattern + are: + + + The publisher sends messages to a queue. + + + The consumer gets the messages in the queue. + + + The consumer can reply with the result of processing + a message by sending another message to the same queue + (queues are duplex by default). + + + The publisher gets replies from the queue. + + + The consumer sends a marker to skip messages + already seen. + + + TTL eventually deletes messages. + + + This pattern is ideal for communicating with a specific + client, especially when a reply is desired from that + client.
@@ -266,15 +297,15 @@ Publish events to any number of subscribers - (publish-subscribe) + (event broadcasting) - Send commands to one or more agents (point-to-point or - publish-subscribe) + Send commands to one or more agents (point-to-point + messaging or event broadcasting) Request an action or get information from a Remote - Procedure Call (RPC) agent + Procedure Call (RPC) agent (point-to-point messaging)
diff --git a/doc/user-guide/zaqar-get-started/os-zaqar-apiGettingStarted.xml b/doc/user-guide/zaqar-get-started/os-zaqar-apiGettingStarted.xml index 9018b62cb..58a1df5ae 100644 --- a/doc/user-guide/zaqar-get-started/os-zaqar-apiGettingStarted.xml +++ b/doc/user-guide/zaqar-get-started/os-zaqar-apiGettingStarted.xml @@ -154,80 +154,109 @@ that messages are handled in a First In, First Out (FIFO) order.
Messaging Patterns - Message Queuing supports a variety of messaging patterns including the - following: + The Message Queuing API supports a variety of + messaging patterns including the following: - producer-consumer + Task distribution - publish-subscribe + Event broadcasting + + + Point-to-point messaging -
- Producer-Consumer - The producer-consumer pattern has the - following characteristics: - - - A producer is programmed to send - messages to a queue. - - - Multiple workers (or consumers) are - programmed to monitor a queue. - - - Only one worker can claim a message - so that no other worker can claim the - message and duplicate the work. - - - The worker must delete the message - when work is done. - - - TTL restores a message to an - unclaimed state if the worker never - finishes. - - - This pattern is ideal for dispatching jobs - to multiple processors. -
-
- Publish-Subscribe - Characteristics of the Publish-Subscribe - pattern are: - - - The publisher sends a message to a - queue. - - - All workers (or subscribers) listen - to the messages in the queue. - - - Workers do not claim a - message. - - - Multiple workers can take action on - a message. - - - Workers can send a marker or cursor - to skip messages already seen. - - - TTL eventually deletes - messages. - - - This pattern is ideal for notification of - events to multiple workers at once. -
+
+
+ Task distribution + The task distribution pattern has the following + characteristics: + + + A producer is programmed to send messages to a + queue. + + + Multiple workers (or consumers) are programmed to + monitor a queue. + + + Only one worker can claim a message so that + no other worker can claim the message and + duplicate the work. + + + The worker must delete the message when work + is done. + + + TTL restores a message to an unclaimed state + if the worker never finishes. + + + This pattern is ideal for dispatching jobs to multiple + processors. +
+
+ Event Broadcasting + Characteristics of the event broadcasting pattern + are: + + + The publisher sends messages to a + queue. + + + Multiple observers (or subscribers) get the + messages in the queue. + + + Multiple observers take action on each + message. + + + Observers send a marker to skip messages + already seen. + + + TTL eventually deletes messages. + + + This pattern is ideal for notification of events to + multiple observers at once. +
+
+ Point-to-point messaging + Characteristics of the point-to-point messaging + pattern are: + + + The publisher sends messages to a queue. + + + The consumer gets the messages in the queue. + + + The consumer can reply with the result of + processing a message by sending another message + to the same queue (queues are duplex by + default). + + + The publisher gets replies from the queue. + + + The consumer sends a marker to skip messages + already seen. + + + TTL eventually deletes messages. + + + This pattern is ideal for communicating with a + specific client, especially when a reply is desired + from that client.
Message Queuing Operations @@ -394,26 +423,25 @@ Following are some generic use cases for Message Queuing: - Distribute tasks among multiple workers - (transactional job queues) + Distribute tasks among multiple workers (transactional + job queues) - Forward events to data collectors - (transactional event queues) + Forward events to data collectors (transactional event + queues) - Publish events to any number of - subscribers (publish-subscribe) + Publish events to any number of subscribers + (event broadcasting) Send commands to one or more agents - (point-to-point or - publish-subscribe) + (point-to-point messaging or event broadcasting) - Request an action or get information - from a Remote Procedure Call (RPC) - agent + Request an action or get information from a Remote + Procedure Call (RPC) agent (point-to-point + messaging)