documentation/manual/en/module_specs/Zend_Service_WindowsAzure_Queue.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.service.windowsazure.storage.queue">
   4     <title>Zend_Service_WindowsAzure_Storage_Queue</title>
   5
   6     <para>
   7         The Queue service stores messages that may be read by any client who has access to the
   8         storage account.
   9     </para>
  10
  11     <para>
  12         A queue can contain an unlimited number of messages, each of which can be up to 8 KB in
  13         size. Messages are generally added to the end of the queue and retrieved from the front of
  14         the queue, although first in/first out (<acronym>FIFO</acronym>) behavior is not guaranteed.
  15         If you need to store messages larger than 8 KB, you can store message data as a queue or in
  16         a table and then store a reference to the data as a message in a queue.
  17     </para>
  18
  19     <para>
  20         Queue Storage is offered by Windows Azure as a <acronym>REST</acronym>
  21         <acronym>API</acronym> which is wrapped by the
  22         <classname>Zend_Service_WindowsAzure_Storage_Queue</classname> class in order to
  23         provide a native <acronym>PHP</acronym> interface to the storage account.
  24     </para>
  25
  26     <sect3 id="zend.service.windowsazure.storage.queue.api">
  27         <title>API Examples</title>
  28
  29         <para>
  30             This topic lists some examples of using the
  31             <classname>Zend_Service_WindowsAzure_Storage_Queue</classname> class. Other features
  32             are available in the download package, as well as a detailed <acronym>API</acronym>
  33             documentation of those features.
  34         </para>
  35
  36         <sect4 id="zend.service.windowsazure.storage.queue.api.create-queue">
  37             <title>Creating a queue</title>
  38
  39             <para>
  40                 Using the following code, a queue can be created on development storage.
  41             </para>
  42
  43             <example id="zend.service.windowsazure.storage.queue.api.create-queue.example">
  44                 <title>Creating a queue</title>
  45
  46                 <programlisting language="php"><![CDATA[
  47 $storageClient = new Zend_Service_WindowsAzure_Storage_Queue();
  48 $result = $storageClient->createQueue('testqueue');
  49
  50 echo 'Queue name is: ' . $result->Name;
  51 ]]></programlisting>
  52             </example>
  53         </sect4>
  54
  55         <sect4 id="zend.service.windowsazure.storage.queue.api.delete-queue">
  56             <title>Deleting a queue</title>
  57
  58             <para>
  59                 Using the following code, a queue can be removed from development storage.
  60             </para>
  61
  62             <example id="zend.service.windowsazure.storage.queue.api.delete-queue.example">
  63                 <title>Deleting a queue</title>
  64
  65                 <programlisting language="php"><![CDATA[
  66 $storageClient = new Zend_Service_WindowsAzure_Storage_Queue();
  67 $storageClient->deleteQueue('testqueue');
  68 ]]></programlisting>
  69             </example>
  70         </sect4>
  71
  72         <sect4 id="zend.service.windowsazure.storage.queue.api.storing-queue">
  73             <title>Adding a message to a queue</title>
  74
  75             <para>
  76                 Using the following code, a message can be added to a queue on development storage.
  77                 Note that the queue has already been created before.
  78             </para>
  79
  80             <example id="zend.service.windowsazure.storage.queue.api.storing-queue.example">
  81                 <title>Adding a message to a queue</title>
  82
  83                 <programlisting language="php"><![CDATA[
  84 $storageClient = new Zend_Service_WindowsAzure_Storage_Queue();
  85
  86 // 3600 = time-to-live of the message, if omitted defaults to 7 days
  87 $storageClient->putMessage('testqueue', 'This is a test message', 3600);
  88 ]]></programlisting>
  89             </example>
  90         </sect4>
  91
  92         <sect4 id="zend.service.windowsazure.storage.queue.api.read-queue">
  93             <title>Reading a message from a queue</title>
  94
  95             <para>
  96                 Using the following code, a message can be read from a queue on development storage.
  97                 Note that the queue and message have already been created before.
  98             </para>
  99
 100             <example id="zend.service.windowsazure.storage.queue.api.read-queue.example">
 101                 <title>Reading a message from a queue</title>
 102
 103                 <programlisting language="php"><![CDATA[
 104 $storageClient = new Zend_Service_WindowsAzure_Storage_Queue();
 105
 106 // retrieve 10 messages at once
 107 $messages = $storageClient->getMessages('testqueue', 10);
 108
 109 foreach ($messages as $message) {
 110     echo $message->MessageText . "\r\n";
 111 }
 112 ]]></programlisting>
 113             </example>
 114
 115             <para>
 116                 The messages that are read using <methodname>getMessages()</methodname> will be
 117                 invisible in the queue for 30 seconds, after which the messages will re-appear in
 118                 the queue. To mark a message as processed and remove it from the queue, use the
 119                 <methodname>deleteMessage()</methodname> method.
 120             </para>
 121
 122             <example id="zend.service.windowsazure.storage.queue.api.read-queue.processexample">
 123                 <title>Marking a message as processed</title>
 124
 125                 <programlisting language="php"><![CDATA[
 126 $storageClient = new Zend_Service_WindowsAzure_Storage_Queue();
 127
 128 // retrieve 10 messages at once
 129 $messages = $storageClient->getMessages('testqueue', 10);
 130
 131 foreach ($messages as $message) {
 132     echo $message . "\r\n";
 133
 134     // Mark the message as processed
 135     $storageClient->deleteMessage('testqueue', $message);
 136 }
 137 ]]></programlisting>
 138             </example>
 139         </sect4>
 140
 141         <sect4 id="zend.service.windowsazure.storage.queue.api.peek-queue">
 142             <title>Check if there are messages in a queue</title>
 143
 144             <para>
 145                 Using the following code, a queue can be checked for new messages. Note that the
 146                 queue and message have already been created before.
 147             </para>
 148
 149             <example id="zend.service.windowsazure.storage.queue.api.peek-queue.example">
 150                 <title>Check if there are messages in a queue</title>
 151
 152                 <programlisting language="php"><![CDATA[
 153 $storageClient = new Zend_Service_WindowsAzure_Storage_Queue();
 154
 155 // retrieve 10 messages at once
 156 $messages = $storageClient->peekMessages('testqueue', 10);
 157
 158 foreach ($messages as $message) {
 159     echo $message->MessageText . "\r\n";
 160 }
 161 ]]></programlisting>
 162             </example>
 163
 164             <para>
 165                 Note that messages that are read using <methodname>peekMessages()</methodname> will
 166                 not become invisible in the queue, nor can they be marked as processed using the
 167                 <methodname>deleteMessage()</methodname> method. To do this, use
 168                 <methodname>getMessages()</methodname> instead.
 169             </para>
 170         </sect4>
 171     </sect3>
 172 </sect2>