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>

154
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">
<title>Producer-Consumer</title>
<para>The producer-consumer pattern has the
following characteristics:</para>
<itemizedlist>
<listitem>
<para>A producer is programmed to send
messages to a queue.</para>
</listitem>
<listitem>
<para>Multiple workers (or consumers) are
programmed to monitor a queue.</para>
</listitem>
<listitem>
<para>Only one worker can claim a message
so that no other worker can claim the
message and duplicate the work.</para>
</listitem>
<listitem>
<para>The worker must delete the message
when work is done.</para>
</listitem>
<listitem>
<para>TTL restores a message to an
unclaimed state if the worker never
finishes.</para>
</listitem>
</itemizedlist>
<para>This pattern is ideal for dispatching jobs
to multiple processors.</para>
</section> </section>
<section xml:id="publish_subscribe"> <section xml:id="task_distribution">
<title>Publish-Subscribe</title> <title>Task distribution</title>
<para>Characteristics of the Publish-Subscribe <para>The task distribution pattern has the following
pattern are:</para> characteristics:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>The publisher sends a message to a <para>A producer is programmed to send messages to a
queue.</para> queue.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>All workers (or subscribers) listen <para>Multiple workers (or consumers) are programmed to
to the messages in the queue.</para> monitor a queue.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Workers do not claim a <para>Only one worker can claim a message so that
no other worker can claim the message and
duplicate the work.</para>
</listitem>
<listitem>
<para>The worker must delete the message when work
is done.</para>
</listitem>
<listitem>
<para>TTL restores a message to an unclaimed state
if the worker never finishes.</para>
</listitem>
</itemizedlist>
<para>This pattern is ideal for dispatching jobs to multiple
processors.</para>
</section>
<section xml:id="event_broadcasting">
<title>Event Broadcasting</title>
<para>Characteristics of the event broadcasting pattern
are:</para>
<itemizedlist>
<listitem>
<para>The publisher sends messages to a
queue.</para>
</listitem>
<listitem>
<para>Multiple observers (or subscribers) get the
messages in the queue.</para>
</listitem>
<listitem>
<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>
<para>TTL eventually deletes
messages.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>This pattern is ideal for notification of <para>This pattern is ideal for notification of events to
events to multiple workers at once.</para> multiple observers at once.</para>
</section> </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 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>