openstack/zaqar
Code Issues Proposed changes

Update use cases to align with dev guide and positioning

Browse Source 
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
This commit is contained in:
kgriffs 2014-08-12 18:06:12 -05:00
parent 278cd1f15b
commit aaae850f5f
2 changed files with 158 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
doc/user-guide/zaqar-api-ref/os-zaqar-apiRef.xml
View File

@ -133,15 +133,18 @@
following:</para> following:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>producer-consumer</para> <para>Task distribution</para>
</listitem> </listitem>
<listitem> <listitem>
<para>publish-subscribe</para> <para>Event broadcasting</para>
</listitem>
<listitem>
<para>Point-to-point messaging</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<section xml:id="producer_consumer"> <section xml:id="task_distribution">
<title>Producer-Consumer</title> <title>Task distribution</title>
<para>The producer-consumer pattern has the following <para>The task distribution pattern has the following
characteristics:</para> characteristics:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -169,27 +172,24 @@
<para>This pattern is ideal for dispatching jobs to multiple <para>This pattern is ideal for dispatching jobs to multiple
processors.</para> processors.</para>
</section> </section>
<section xml:id="publish_subscribe"> <section xml:id="event_broadcasting">
<title>Publish-Subscribe</title> <title>Event broadcasting</title>
<para>Characteristics of the Publish-Subscribe pattern <para>Characteristics of the event broadcasting pattern
are:</para> are:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>The publisher sends a message to a queue.</para> <para>The publisher sends messages to a queue.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>All workers (or subscribers) listen to the messages <para>Multiple observers get the messages
in the queue.</para> in the queue.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Workers do not claim a message.</para> <para>Multiple observers take action on each
</listitem>
<listitem>
<para>Multiple workers can take action on a
message.</para> message.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Workers can send a marker or cursor to skip messages <para>Observers send a marker to skip messages
already seen.</para> already seen.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -197,7 +197,38 @@
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>This pattern is ideal for notification of events to <para>This pattern is ideal for notification of events to
multiple workers at once.</para> multiple observers at once.</para>
</section>
<section xml:id="point_to_point">
<title>Point-to-point messaging</title>
<para>Characteristics of the point-to-point messaging pattern
are:</para>
<itemizedlist>
<listitem>
<para>The publisher sends messages to a queue.</para>
</listitem>
<listitem>
<para>The consumer gets the messages in the queue.</para>
</listitem>
<listitem>
<para>The consumer can reply with the result of processing
a message by sending another message to the same queue
(queues are duplex by default).</para>
</listitem>
<listitem>
<para>The publisher gets replies from the queue.</para>
</listitem>
<listitem>
<para>The consumer sends a marker to skip messages
already seen.</para>
</listitem>
<listitem>
<para>TTL eventually deletes messages.</para>
</listitem>
</itemizedlist>
<para>This pattern is ideal for communicating with a specific
client, especially when a reply is desired from that
client.</para>
</section> </section>
</section> </section>
<section xml:id="Use-Cases-d1e001"> <section xml:id="Use-Cases-d1e001">
@ -266,15 +297,15 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Publish events to any number of subscribers <para>Publish events to any number of subscribers
(publish-subscribe)</para> (event broadcasting)</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Send commands to one or more agents (point-to-point or <para>Send commands to one or more agents (point-to-point
publish-subscribe)</para> messaging or event broadcasting)</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Request an action or get information from a Remote <para>Request an action or get information from a Remote
Procedure Call (RPC) agent</para> Procedure Call (RPC) agent (point-to-point messaging)</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>

186
doc/user-guide/zaqar-get-started/os-zaqar-apiGettingStarted.xml
View File

@ -154,80 +154,109 @@
that messages are handled in a First In, First Out (FIFO) order.</para> that messages are handled in a First In, First Out (FIFO) order.</para>
<section xml:id="operating_modes"> <section xml:id="operating_modes">
<title>Messaging Patterns</title> <title>Messaging Patterns</title>
<para>Message Queuing supports a variety of messaging patterns including the <para>The Message Queuing API supports a variety of
following:</para> messaging patterns including the following:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>producer-consumer</para> <para>Task distribution</para>
</listitem> </listitem>
<listitem> <listitem>
<para>publish-subscribe</para> <para>Event broadcasting</para>
</listitem>
<listitem>
<para>Point-to-point messaging</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<section xml:id="producer_consumer"> </section>
<title>Producer-Consumer</title> <section xml:id="task_distribution">
<para>The producer-consumer pattern has the <title>Task distribution</title>
following characteristics:</para> <para>The task distribution pattern has the following
<itemizedlist> characteristics:</para>
<listitem> <itemizedlist>
<para>A producer is programmed to send <listitem>
messages to a queue.</para> <para>A producer is programmed to send messages to a
</listitem> queue.</para>
<listitem> </listitem>
<para>Multiple workers (or consumers) are <listitem>
programmed to monitor a queue.</para> <para>Multiple workers (or consumers) are programmed to
</listitem> monitor a queue.</para>
<listitem> </listitem>
<para>Only one worker can claim a message <listitem>
so that no other worker can claim the <para>Only one worker can claim a message so that
message and duplicate the work.</para> no other worker can claim the message and
</listitem> duplicate the work.</para>
<listitem> </listitem>
<para>The worker must delete the message <listitem>
when work is done.</para> <para>The worker must delete the message when work
</listitem> is done.</para>
<listitem> </listitem>
<para>TTL restores a message to an <listitem>
unclaimed state if the worker never <para>TTL restores a message to an unclaimed state
finishes.</para> if the worker never finishes.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>This pattern is ideal for dispatching jobs <para>This pattern is ideal for dispatching jobs to multiple
to multiple processors.</para> processors.</para>
</section> </section>
<section xml:id="publish_subscribe"> <section xml:id="event_broadcasting">
<title>Publish-Subscribe</title> <title>Event Broadcasting</title>
<para>Characteristics of the Publish-Subscribe <para>Characteristics of the event broadcasting pattern
pattern are:</para> are:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>The publisher sends a message to a <para>The publisher sends messages to a
queue.</para> queue.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>All workers (or subscribers) listen <para>Multiple observers (or subscribers) get the
to the messages in the queue.</para> messages in the queue.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Workers do not claim a <para>Multiple observers take action on each
message.</para> message.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Multiple workers can take action on <para>Observers send a marker to skip messages
a message.</para> already seen.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Workers can send a marker or cursor <para>TTL eventually deletes messages.</para>
to skip messages already seen.</para> </listitem>
</listitem> </itemizedlist>
<listitem> <para>This pattern is ideal for notification of events to
<para>TTL eventually deletes multiple observers at once.</para>
messages.</para> </section>
</listitem> <section xml:id="point_to_point">
</itemizedlist> <title>Point-to-point messaging</title>
<para>This pattern is ideal for notification of <para>Characteristics of the point-to-point messaging
events to multiple workers at once.</para> pattern are:</para>
</section> <itemizedlist>
<listitem>
<para>The publisher sends messages to a queue.</para>
</listitem>
<listitem>
<para>The consumer gets the messages in the queue.</para>
</listitem>
<listitem>
<para>The consumer can reply with the result of
processing a message by sending another message
to the same queue (queues are duplex by
default).</para>
</listitem>
<listitem>
<para>The publisher gets replies from the queue.</para>
</listitem>
<listitem>
<para>The consumer sends a marker to skip messages
already seen.</para>
</listitem>
<listitem>
<para>TTL eventually deletes messages.</para>
</listitem>
</itemizedlist>
<para>This pattern is ideal for communicating with a
specific client, especially when a reply is desired
from that client.</para>
</section> </section>
<section xml:id="cloud-queuing-actions"> <section xml:id="cloud-queuing-actions">
<title>Message Queuing Operations</title> <title>Message Queuing Operations</title>
@ -394,26 +423,25 @@
<para>Following are some generic use cases for Message Queuing:</para> <para>Following are some generic use cases for Message Queuing:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Distribute tasks among multiple workers <para>Distribute tasks among multiple workers (transactional
(transactional job queues)</para> job queues)</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Forward events to data collectors <para>Forward events to data collectors (transactional event
(transactional event queues)</para> queues)</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Publish events to any number of <para>Publish events to any number of subscribers
subscribers (publish-subscribe)</para> (event broadcasting)</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Send commands to one or more agents <para>Send commands to one or more agents
(point-to-point or (point-to-point messaging or event broadcasting)</para>
publish-subscribe)</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Request an action or get information <para>Request an action or get information from a Remote
from a Remote Procedure Call (RPC) Procedure Call (RPC) agent (point-to-point
agent</para> messaging)</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>