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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.queue.adapters">
   4     <title>Adapters</title>
   5
   6     <para>
   7         <classname>Zend_Queue</classname> supports all queues implementing the
   8         interface <classname>Zend_Queue_Adapter_AdapterInterface</classname>.
   9         The following Message Queue services are supported:
  10     </para>
  11
  12     <itemizedlist>
  13         <listitem>
  14             <para>
  15                 <ulink url="http://activemq.apache.org/">Apache ActiveMQ</ulink>.
  16             </para>
  17         </listitem>
  18
  19         <listitem>
  20             <para>
  21                 A database driven queue via <classname>Zend_Db</classname>.
  22             </para>
  23         </listitem>
  24
  25         <listitem>
  26             <para>
  27                 A <ulink url="http://memcachedb.org/memcacheq/">MemcacheQ</ulink>
  28                 queue driven via <classname>Memcache</classname>.
  29             </para>
  30         </listitem>
  31
  32         <listitem>
  33             <para>
  34                 <ulink url="http://www.zend.com/en/products/platform/">Zend Platform's</ulink> Job
  35                 Queue.
  36             </para>
  37         </listitem>
  38
  39         <listitem>
  40             <para>
  41                 A local array. Useful for unit testing.
  42             </para>
  43         </listitem>
  44     </itemizedlist>
  45
  46     <note id="zend.queue.adapters.limitations">
  47         <title>Limitations</title>
  48
  49         <para>
  50             Message transaction handling is not supported.
  51         </para>
  52     </note>
  53
  54     <sect2 id="zend.queue.adapters.configuration">
  55         <title>Specific Adapters - Configuration settings</title>
  56
  57         <para>
  58             If a default setting is indicated then the parameter is optional.
  59             If a default setting is not specified then the parameter is
  60             required.
  61         </para>
  62
  63         <sect3 id="zend.queue.adapters.configuration.activemq">
  64             <title>Apache ActiveMQ - Zend_Queue_Adapter_Activemq</title>
  65
  66             <para>
  67                 Options listed here are known requirements. Not all
  68                 messaging servers require username or password.
  69             </para>
  70
  71             <itemizedlist>
  72                 <listitem>
  73                     <para>
  74                          <emphasis>$options['name'] = '/temp/queue1';</emphasis>
  75                     </para>
  76
  77                     <para>
  78                         This is the name of the queue that you wish to start
  79                         using. (Required)
  80                     </para>
  81                 </listitem>
  82
  83                 <listitem>
  84                     <para>
  85                         <emphasis>$options['driverOptions']['host'] = 'host.domain.tld';</emphasis>
  86                     </para>
  87
  88                     <para>
  89                         <emphasis>$options['driverOptions']['host'] = '127.0.0.1';</emphasis>
  90                     </para>
  91
  92                     <para>
  93                         You may set host to an IP address or a hostname.
  94                     </para>
  95
  96                     <para>
  97                         Default setting for host is '127.0.0.1'.
  98                     </para>
  99                 </listitem>
 100
 101                 <listitem>
 102                     <para>
 103                         <emphasis>$options['driverOptions']['port'] = 61613;</emphasis>
 104                     </para>
 105
 106                     <para>Default setting for port is 61613.</para>
 107                 </listitem>
 108
 109                 <listitem>
 110                     <para>
 111                          <emphasis>$options['driverOptions']['username'] = 'username';</emphasis>
 112                     </para>
 113
 114                     <para>
 115                         Optional for some messaging servers. Read the manual
 116                         for your messaging server.
 117                     </para>
 118                 </listitem>
 119
 120                 <listitem>
 121                     <para>
 122                         <emphasis>$options['driverOptions']['password'] = 'password';</emphasis>
 123                     </para>
 124
 125                     <para>
 126                         Optional for some messaging servers. Read the manual
 127                         for your messaging server.
 128                     </para>
 129                 </listitem>
 130
 131                 <listitem>
 132                     <para>
 133                         <emphasis>$options['driverOptions']['timeout_sec'] = 2;</emphasis>
 134                     </para>
 135
 136                     <para>
 137                         <emphasis>$options['driverOptions']['timeout_usec'] = 0;</emphasis>
 138                     </para>
 139
 140                     <para>
 141                         This is the amount of time that
 142                         <classname>Zend_Queue_Adapter_Activemq</classname> will wait for
 143                         read activity on a socket before returning no messages.
 144                     </para>
 145                 </listitem>
 146             </itemizedlist>
 147         </sect3>
 148
 149         <sect3 id="zend.queue.adapters.configuration.Db">
 150             <title>Db - Zend_Queue_Adapter_Db</title>
 151
 152             <para>
 153                 Driver options are checked for a few required options such
 154                 as <emphasis>type</emphasis>, <emphasis>host</emphasis>,
 155                 <emphasis>username</emphasis>, <emphasis>password</emphasis>,
 156                 and <emphasis>dbname</emphasis>. You may pass along
 157                 additional parameters for <methodname>Zend_DB::factory()</methodname> as parameters
 158                 in <varname>$options['driverOptions']</varname>. An example of an additional
 159                 option not listed here, but could be passed would be <emphasis>port</emphasis>.
 160             </para>
 161
 162             <programlisting language="php"><![CDATA[
 163 $options = array(
 164     'driverOptions' => array(
 165         'host'      => 'db1.domain.tld',
 166         'username'  => 'my_username',
 167         'password'  => 'my_password',
 168         'dbname'    => 'messaging',
 169         'type'      => 'pdo_mysql',
 170         'port'      => 3306, // optional parameter.
 171     ),
 172     'options' => array(
 173         // use Zend_Db_Select for update, not all databases can support this
 174         // feature.
 175         Zend_Db_Select::FOR_UPDATE => true
 176     )
 177 );
 178
 179 // Create a database queue.
 180 $queue = new Zend_Queue('Db', $options);
 181 ]]></programlisting>
 182
 183             <itemizedlist>
 184                 <listitem>
 185                     <para>
 186                          <emphasis>$options['name'] = 'queue1';</emphasis>
 187                     </para>
 188
 189                     <para>
 190                         This is the name of the queue that you wish to start using. (Required)
 191                     </para>
 192                 </listitem>
 193
 194                 <listitem>
 195                     <para>
 196                         <emphasis>$options['driverOptions']['type'] = 'Pdo';</emphasis>
 197                     </para>
 198
 199                     <para>
 200                         <emphasis>type</emphasis> is the adapter you wish to have
 201                         <methodname>Zend_Db::factory()</methodname> use. This is
 202                         the first parameter for the
 203                         <methodname>Zend_Db::factory()</methodname> class
 204                         method call.
 205                     </para>
 206                 </listitem>
 207
 208                 <listitem>
 209                     <para>
 210                         <emphasis>$options['driverOptions']['host'] = 'host.domain.tld';</emphasis>
 211                     </para>
 212
 213                     <para>
 214                         <emphasis>$options['driverOptions']['host'] = '127.0.0.1';</emphasis>
 215                     </para>
 216
 217                     <para>You may set host to an IP address or a hostname.</para>
 218
 219                     <para>Default setting for host is '127.0.0.1'.</para>
 220                 </listitem>
 221
 222                 <listitem>
 223                     <para>
 224                          <emphasis>$options['driverOptions']['username'] = 'username';</emphasis>
 225                     </para>
 226                 </listitem>
 227
 228                 <listitem>
 229                     <para>
 230                         <emphasis>$options['driverOptions']['password'] = 'password';</emphasis>
 231                     </para>
 232                 </listitem>
 233
 234                 <listitem>
 235                     <para>
 236                         <emphasis>$options['driverOptions']['dbname'] = 'dbname';</emphasis>
 237                     </para>
 238
 239                     <para>
 240                         The database name that you have created the required tables for.
 241                         See the notes section below.
 242                     </para>
 243                 </listitem>
 244             </itemizedlist>
 245         </sect3>
 246
 247         <sect3 id="zend.queue.adapters.configuration.memcacheq">
 248             <title>MemcacheQ - Zend_Queue_Adapter_Memcacheq</title>
 249
 250             <itemizedlist>
 251                 <listitem>
 252                     <para>
 253                          <emphasis>$options['name'] = 'queue1';</emphasis>
 254                     </para>
 255
 256                     <para>
 257                         This is the name of the queue that you wish to start using. (Required)
 258                     </para>
 259                 </listitem>
 260
 261                 <listitem>
 262                     <para>
 263                          <emphasis>$options['driverOptions']['host'] = 'host.domain.tld';</emphasis>
 264                     </para>
 265
 266                     <para>
 267                          <emphasis>$options['driverOptions']['host'] = '127.0.0.1;'</emphasis>
 268                     </para>
 269
 270                     <para>You may set host to an IP address or a hostname.</para>
 271
 272                     <para>Default setting for host is '127.0.0.1'.</para>
 273                 </listitem>
 274
 275                 <listitem>
 276                     <para>
 277                         <emphasis>$options['driverOptions']['port'] = 22201;</emphasis>
 278                     </para>
 279
 280                     <para>The default setting for port is 22201.</para>
 281                 </listitem>
 282             </itemizedlist>
 283         </sect3>
 284
 285         <sect3 id="zend.queue.adapters.configuration.platformjq">
 286             <title>Zend Platform Job Queue - Zend_Queue_Adapter_PlatformJobQueue</title>
 287
 288             <itemizedlist>
 289                 <listitem>
 290                     <para>
 291                          <emphasis>$options['daemonOptions']['host'] = '127.0.0.1:10003';</emphasis>
 292                     </para>
 293
 294                     <para>
 295                         The hostname and port corresponding to the Zend Platform Job Queue daemon
 296                         you will use. (Required)
 297                     </para>
 298                 </listitem>
 299
 300                 <listitem>
 301                     <para>
 302                          <emphasis>$options['daemonOptions']['password'] = '1234';</emphasis>
 303                     </para>
 304
 305                     <para>
 306                         The password required for accessing the Zend Platform Job Queue daemon.
 307                         (Required)
 308                     </para>
 309                 </listitem>
 310             </itemizedlist>
 311         </sect3>
 312
 313         <sect3 id="zend.queue.adapters.configuration.array">
 314             <title>Array - Zend_Queue_Adapter_Array</title>
 315
 316             <itemizedlist>
 317                 <listitem>
 318                     <para>
 319                          <emphasis>$options['name'] = 'queue1';</emphasis>
 320                     </para>
 321
 322                     <para>
 323                         This is the name of the queue that you wish to start using. (Required)
 324                     </para>
 325                 </listitem>
 326             </itemizedlist>
 327         </sect3>
 328     </sect2>
 329
 330     <sect2 id="zend.queue.adapters.notes">
 331         <title>Notes for Specific Adapters</title>
 332
 333         <para>The following adapters have notes:</para>
 334
 335         <sect3 id="zend.queue.adapters.notes.activemq">
 336             <title>Apache ActiveMQ</title>
 337
 338             <para>
 339                 Visibility duration for
 340                 <classname>Zend_Queue_Adapter_Activemq</classname> is not
 341                 available.
 342             </para>
 343
 344             <para>
 345                 While Apache's ActiveMQ will support multiple subscriptions, the
 346                 <classname>Zend_Queue</classname> does not. You must create a
 347                 new <classname>Zend_Queue</classname> object for each individual
 348                 subscription.
 349             </para>
 350
 351             <para>
 352                 ActiveMQ queue/topic names must begin with one of:
 353             </para>
 354
 355             <itemizedlist>
 356                 <listitem>
 357                     <para>
 358                         <filename>/queue/</filename>
 359                     </para>
 360                 </listitem>
 361
 362                 <listitem>
 363                     <para>
 364                         <filename>/topic/</filename>
 365                     </para>
 366                 </listitem>
 367
 368                 <listitem>
 369                     <para>
 370                         <filename>/temp-queue/</filename>
 371                     </para>
 372                 </listitem>
 373
 374                 <listitem>
 375                     <para>
 376                         <filename>/temp-topic/</filename>
 377                     </para>
 378                 </listitem>
 379             </itemizedlist>
 380
 381             <para>
 382                 For example: <filename>/queue/testing</filename>
 383             </para>
 384
 385             <para>
 386                 The following functions are not supported:
 387             </para>
 388
 389             <itemizedlist>
 390                 <listitem>
 391                     <para>
 392                          <methodname>create()</methodname> - create queue.
 393                          Calling this function will throw an exception.
 394                     </para>
 395                 </listitem>
 396
 397                 <listitem>
 398                     <para>
 399                         <methodname>delete()</methodname> - delete queue.
 400                         Calling this function will throw an exception.
 401                     </para>
 402                 </listitem>
 403
 404                 <listitem>
 405                     <para>
 406                         <methodname>getQueues()</methodname> - list queues.
 407                         Calling this function will throw an exception.
 408                     </para>
 409                 </listitem>
 410             </itemizedlist>
 411         </sect3>
 412
 413         <sect3 id="zend.queue.adapters.notes.zend_db">
 414             <title>Zend_Db</title>
 415
 416             <para>
 417                 The database <emphasis>CREATE TABLE ( ... )</emphasis> <acronym>SQL</acronym>
 418                 statement can be found in <filename>Zend/Queue/Adapter/Db/mysql.sql</filename>.
 419             </para>
 420         </sect3>
 421
 422         <sect3 id="zend.queue.adapters.notes.memcacheQ">
 423             <title>MemcacheQ</title>
 424
 425             <para>
 426                 Memcache can be downloaded from <ulink
 427                     url="http://www.danga.com/memcached/">http://www.danga.com/memcached/</ulink>.
 428             </para>
 429
 430             <para>
 431                 MemcacheQ can be downloaded from <ulink
 432                     url="http://memcachedb.org/memcacheq/">http://memcachedb.org/memcacheq/</ulink>.
 433             </para>
 434
 435             <itemizedlist>
 436                 <listitem>
 437                     <para>
 438                         <methodname>deleteMessage()</methodname> - Messages are deleted upon
 439                         reception from the queue. Calling this function would
 440                         have no effect. Calling this function will throw an
 441                         error.
 442                     </para>
 443                 </listitem>
 444
 445                 <listitem>
 446                     <para>
 447                         <methodname>count()</methodname> or <methodname>count($adapter)</methodname>
 448                         - MemcacheQ does not support a method for counting the number of items in
 449                         a queue. Calling this function will throw an error.
 450                     </para>
 451                 </listitem>
 452             </itemizedlist>
 453         </sect3>
 454
 455         <sect3 id="zend.queue.adapters.notes.platformjq">
 456             <title>Zend Platform Job Queue</title>
 457
 458             <para>
 459                 Job Queue is a feature of Zend Platform's Enterprise Solution offering. It is not a
 460                 traditional message queue, and instead allows you to queue a script to execute,
 461                 along with the parameters you wish to pass to it. You can find out more about Job
 462                 Queue <ulink url="http://www.zend.com/en/products/platform/">on the zend.com
 463                     website</ulink>.
 464             </para>
 465
 466             <para>
 467                 The following is a list of methods where this adapter's behavior diverges from the
 468                 standard offerings:
 469             </para>
 470
 471             <itemizedlist>
 472                 <listitem>
 473                     <para>
 474                         <methodname>create()</methodname> - Zend Platform does not have the concept
 475                         of discrete queues; instead, it allows administrators to provide scripts for
 476                         processing jobs. Since adding new scripts is restricted to the
 477                         administration interface, this method simply throws an exception indicating
 478                         the action is forbidden.
 479                     </para>
 480                 </listitem>
 481
 482                 <listitem>
 483                     <para>
 484                         <methodname>isExists()</methodname> - Just like
 485                         <methodname>create()</methodname>, since Job Queue does not have a notion of
 486                         named queues, this method throws an exception when invoked.
 487                     </para>
 488                 </listitem>
 489
 490                 <listitem>
 491                     <para>
 492                         <methodname>delete()</methodname> - similar to
 493                         <methodname>create()</methodname>, deletion of JQ scripts is not possible
 494                         except via the admin interface; this method raises an exception.
 495                     </para>
 496                 </listitem>
 497
 498                 <listitem>
 499                     <para>
 500                         <methodname>getQueues()</methodname> - Zend Platform does not allow
 501                         introspection into the attached job handling scripts via the
 502                         <acronym>API</acronym>. This method throws an exception.
 503                     </para>
 504                 </listitem>
 505
 506                 <listitem>
 507                     <para>
 508                         <methodname>count()</methodname> - returns the total number of jobs
 509                         currently active in the Job Queue.
 510                     </para>
 511                 </listitem>
 512
 513                 <listitem>
 514                     <para>
 515                         <methodname>send()</methodname> - this method is perhaps the one method that
 516                         diverges most from other adapters. The <varname>$message</varname> argument
 517                         may be one of three possible types, and will operate differently based on
 518                         the value passed:
 519                     </para>
 520
 521                     <itemizedlist>
 522                         <listitem>
 523                             <para>
 524                                 <acronym>string</acronym> - the name of a script registered with Job
 525                                 Queue to invoke. If passed in this way, no arguments are provided to
 526                                 the script.
 527                             </para>
 528                         </listitem>
 529
 530                         <listitem>
 531                             <para>
 532                                 <acronym>array</acronym> - an array of values with which to
 533                                 configure a <classname>ZendApi_Job</classname> object. These may
 534                                 include the following:
 535                             </para>
 536
 537                             <itemizedlist>
 538                                 <listitem>
 539                                     <para>
 540                                         <varname>script</varname> - the name of the Job Queue script
 541                                         to invoke. (Required)
 542                                     </para>
 543                                 </listitem>
 544
 545                                 <listitem>
 546                                     <para>
 547                                         <varname>priority</varname> - the job priority to use when
 548                                         registering with the queue.
 549                                     </para>
 550                                 </listitem>
 551
 552                                 <listitem>
 553                                     <para>
 554                                         <varname>name</varname> - a short string describing the job.
 555                                     </para>
 556                                 </listitem>
 557
 558                                 <listitem>
 559                                     <para>
 560                                         <varname>predecessor</varname> - the ID of a job on which
 561                                         this one depends, and which must be executed before this one
 562                                         may begin.
 563                                     </para>
 564                                 </listitem>
 565
 566                                 <listitem>
 567                                     <para>
 568                                         <varname>preserved</varname> - whether or not to retain the
 569                                         job within the Job Queue history. By default, off; pass a
 570                                         <constant>TRUE</constant> value to retain it.
 571                                     </para>
 572                                 </listitem>
 573
 574                                 <listitem>
 575                                     <para>
 576                                         <varname>user_variables</varname> - an associative array of
 577                                         all variables you wish to have in scope during job execution
 578                                         (similar to named arguments).
 579                                     </para>
 580                                 </listitem>
 581
 582                                 <listitem>
 583                                     <para>
 584                                         <varname>interval</varname> - how often, in seconds, the job
 585                                         should run. By default, this is set to 0, indicating it
 586                                         should run once, and once only.
 587                                     </para>
 588                                 </listitem>
 589
 590                                 <listitem>
 591                                     <para>
 592                                         <varname>end_time</varname> - an expiry time, past which the
 593                                         job should not run. If the job was set to run only once,
 594                                         and <varname>end_time</varname> has passed, then the job
 595                                         will not be executed. If the job was set to run on an
 596                                         interval, it will not execute again once
 597                                         <varname>end_time</varname> has passed.
 598                                     </para>
 599                                 </listitem>
 600
 601                                 <listitem>
 602                                     <para>
 603                                         <varname>schedule_time</varname> - a <acronym>UNIX</acronym>
 604                                         timestamp indicating when to run the job; by default, 0,
 605                                         indicating the job should run as soon as possible.
 606                                     </para>
 607                                 </listitem>
 608
 609                                 <listitem>
 610                                     <para>
 611                                         <varname>application_id</varname> - the application
 612                                         identifier of the job. By default, this is
 613                                         <constant>NULL</constant>, indicating that one will be
 614                                         automatically assigned by the queue, if the queue was
 615                                         assigned an application ID.
 616                                     </para>
 617                                 </listitem>
 618                             </itemizedlist>
 619
 620                             <para>
 621                                 As noted, only the <varname>script</varname> argument is required;
 622                                 all others are simply available to allow passing more fine-grained
 623                                 detail on how and when to run the job.
 624                             </para>
 625                         </listitem>
 626
 627                         <listitem>
 628                             <para>
 629                                 <classname>ZendApi_Job</classname> - finally, you may simply pass a
 630                                 <classname>ZendApi_Job</classname> instance, and it will be passed
 631                                 along to Platform's Job Queue.
 632                             </para>
 633                         </listitem>
 634                     </itemizedlist>
 635
 636                     <para>
 637                         In all instances, <methodname>send()</methodname> returns a
 638                         <classname>Zend_Queue_Message_PlatformJob</classname> object, which provides
 639                         access to the <classname>ZendApi_Job</classname> object used to communicate
 640                         with Job Queue.
 641                     </para>
 642                 </listitem>
 643
 644                 <listitem>
 645                     <para>
 646                         <methodname>receive()</methodname> - retrieves a list of active jobs from
 647                         Job Queue. Each job in the returned set will be an instance of
 648                         <classname>Zend_Queue_Message_PlatformJob</classname>.
 649                     </para>
 650                 </listitem>
 651
 652                 <listitem>
 653                     <para>
 654                         <methodname>deleteMessage()</methodname> - since this adapter only works
 655                         with Job Queue, this method expects the provided <varname>$message</varname>
 656                         to be a <classname>Zend_Queue_Message_PlatformJob</classname> instance, and
 657                         will throw an exception otherwise.
 658                     </para>
 659                 </listitem>
 660             </itemizedlist>
 661         </sect3>
 662
 663         <sect3 id="zend.queue.adapters.notes.array">
 664             <title>Array (local)</title>
 665
 666             <para>
 667                 The Array queue is a <acronym>PHP</acronym> <methodname>array()</methodname>
 668                 in local memory. The <classname>Zend_Queue_Adapter_Array</classname> is good for
 669                 unit testing.
 670             </para>
 671         </sect3>
 672     </sect2>
 673 </sect1>