documentation/manual/en/module_specs/Zend_Queue-Framework.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.queue.framework">
   4     <title>Framework</title>
   5
   6     <para>
   7         The <classname>Zend_Queue</classname> is a proxy that hides the details
   8         of the queue services. The queue services are represented by
   9         <classname>Zend_Queue_Adapter_&lt;service&gt;</classname>. For example,
  10         <classname>Zend_Queue_Adapter_Db</classname> is a queue that will use
  11         database tables to store and retrieve messages.
  12     </para>
  13
  14     <para>
  15         Below is an example for using database tables for a queuing system:
  16     </para>
  17
  18     <programlisting language="php"><![CDATA[
  19 $options = array(
  20     'name'          => 'queue1',
  21     'driverOptions' => array(
  22         'host'      => '127.0.0.1',
  23         'port'      => '3306',
  24         'username'  => 'queue',
  25         'password'  => 'queue',
  26         'dbname'    => 'queue',
  27         'type'      => 'pdo_mysql'
  28     )
  29 );
  30
  31 // Create a database queue.
  32 // Zend_Queue will prepend Zend_Queue_Adapter_ to 'Db' for the class name.
  33 $queue = new Zend_Queue('Db', $options);
  34 ]]></programlisting>
  35
  36     <para>
  37         The <classname>Zend_Queue</classname> constructor will create a
  38         <classname>Zend_Queue_Adapter_Db</classname> and initialize the adapter
  39         with the configuration settings.
  40     </para>
  41
  42     <para>
  43         The accepted configuration settings for each adapter are provided
  44         in the <link linkend="zend.queue.adapters">adapter notes</link>.
  45     </para>
  46
  47     <para>
  48         <classname>Zend_Queue</classname> returns messages using the class
  49         <classname>Zend_Queue_Message_Iterator</classname>, which is an
  50         implementation of <acronym>SPL</acronym> <classname>Iterator</classname> and
  51         <classname>Countable</classname>.
  52         <classname>Zend_Queue_Message_Iterator</classname> contains an array of
  53         <classname>Zend_Queue_Message</classname> objects.
  54     </para>
  55
  56     <programlisting language="php"><![CDATA[
  57 $messages = $queue->receive(5);
  58 foreach ($messages as $i => $message) {
  59     echo "$i) Message => ", $message->body, "\n";
  60 }
  61 ]]></programlisting>
  62
  63     <para>
  64         Any exceptions thrown are of class
  65         <classname>Zend_Queue_Exception</classname>.
  66     </para>
  67
  68     <sect2 id="zend.queue.framework.basics">
  69         <title>Introduction</title>
  70
  71         <para>
  72             <classname>Zend_Queue</classname> is a proxy class that represents
  73             an adapter.
  74         </para>
  75
  76         <para>
  77             The <methodname>send()</methodname>,
  78             <methodname>count($queue)</methodname>, and
  79             <methodname>receive()</methodname> methods are employed by each
  80             adapter to interact with queues.
  81         </para>
  82
  83         <para>
  84             The <methodname>createQueue()</methodname>,
  85             <methodname>deleteQueue()</methodname> methods are used to manage
  86             queues.
  87         </para>
  88     </sect2>
  89
  90     <sect2 id="zend.queue.framework.support">
  91         <title>Commonality among adapters</title>
  92
  93         <para>
  94             The queue services supported by <classname>Zend_Queue</classname> do
  95             not all support the same functions. For example,
  96             <classname>Zend_Queue_Adapter_Array</classname>,
  97             <classname>Zend_Queue_Adapter_Db</classname>, support all functions,
  98             while <classname>Zend_Queue_Adapter_Activemq</classname> does not
  99             support queue listing, queue deletion, or counting of messages.
 100         </para>
 101
 102         <para>
 103             You can determine what functions are supported by using
 104             <methodname>Zend_Queue::isSupported()</methodname> or
 105             <methodname>Zend_Queue::getCapabilities()</methodname>.
 106         </para>
 107
 108         <itemizedlist>
 109             <listitem>
 110                 <para>
 111                     <emphasis><methodname>createQueue()</methodname></emphasis> - create a queue
 112                 </para>
 113             </listitem>
 114
 115             <listitem>
 116                 <para>
 117                     <emphasis><methodname>deleteQueue()</methodname></emphasis> - delete a queue
 118                 </para>
 119             </listitem>
 120
 121             <listitem>
 122                 <para>
 123                     <emphasis><methodname>send()</methodname></emphasis> - send a message
 124                 </para>
 125
 126                 <para>
 127                     <methodname>send()</methodname> is not available in all adapters; the
 128                     <classname>Zend_Queue_Adapter_Null</classname> does not
 129                     support <methodname>send()</methodname>.
 130                 </para>
 131             </listitem>
 132
 133             <listitem>
 134                 <para>
 135                     <emphasis><methodname>receive()</methodname></emphasis> - receive messages
 136                 </para>
 137
 138                 <para>
 139                     <methodname>receive()</methodname> is not available in all adapters;
 140                     the <classname>Zend_Queue_Adapter_Null</classname> does not
 141                     support <methodname>receive()</methodname>.
 142                 </para>
 143             </listitem>
 144
 145             <listitem>
 146                 <para>
 147                     <emphasis><methodname>deleteMessage()</methodname></emphasis> - delete a
 148                     message
 149                 </para>
 150             </listitem>
 151
 152             <listitem>
 153                 <para>
 154                     <emphasis><methodname>count()</methodname></emphasis> - count the number of
 155                     messages in a queue
 156                 </para>
 157             </listitem>
 158
 159             <listitem>
 160                 <para>
 161                     <emphasis><methodname>isExists()</methodname></emphasis> - checks the existence
 162                     of a queue
 163                 </para>
 164             </listitem>
 165         </itemizedlist>
 166
 167         <para>
 168             <methodname>receive()</methodname> methods are employed by each
 169             adapter to interact with queues.
 170         </para>
 171
 172         <para>
 173             The <methodname>createQueue()</methodname> and
 174             <methodname>deleteQueue()</methodname> methods are used to manage
 175             queues.
 176         </para>
 177     </sect2>
 178 </sect1>