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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.queue.adapters">
    <title>Adapters</title>

    <para>
        <classname>Zend_Queue</classname> supports all queues implementing the
        interface <classname>Zend_Queue_Adapter_AdapterInterface</classname>.
        The following Message Queue services are supported:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <ulink url="http://activemq.apache.org/">Apache ActiveMQ</ulink>.
            </para>
        </listitem>

        <listitem>
            <para>
                A database driven queue via <classname>Zend_Db</classname>.
            </para>
        </listitem>

        <listitem>
            <para>
                A <ulink url="http://memcachedb.org/memcacheq/">MemcacheQ</ulink>
                queue driven via <classname>Memcache</classname>.
            </para>
        </listitem>

        <listitem>
            <para>
                <ulink url="http://www.zend.com/en/products/platform/">Zend Platform's</ulink> Job
                Queue.
            </para>
        </listitem>

        <listitem>
            <para>
                A local array. Useful for unit testing.
            </para>
        </listitem>
    </itemizedlist>

    <note id="zend.queue.adapters.limitations">
        <title>Limitations</title>

        <para>
            Message transaction handling is not supported.
        </para>
    </note>

    <sect2 id="zend.queue.adapters.configuration">
        <title>Specific Adapters - Configuration settings</title>

        <para>
            If a default setting is indicated then the parameter is optional.
            If a default setting is not specified then the parameter is
            required.
        </para>

        <sect3 id="zend.queue.adapters.configuration.activemq">
            <title>Apache ActiveMQ - Zend_Queue_Adapter_Activemq</title>

            <para>
                Options listed here are known requirements. Not all
                messaging servers require username or password.
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                         <emphasis>$options['name'] = '/temp/queue1';</emphasis>
                    </para>

                    <para>
                        This is the name of the queue that you wish to start
                        using. (Required)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>$options['driverOptions']['host'] = 'host.domain.tld';</emphasis>
                    </para>

                    <para>
                        <emphasis>$options['driverOptions']['host'] = '127.0.0.1';</emphasis>
                    </para>

                    <para>
                        You may set host to an IP address or a hostname.
                    </para>

                    <para>
                        Default setting for host is '127.0.0.1'.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>$options['driverOptions']['port'] = 61613;</emphasis>
                    </para>

                    <para>Default setting for port is 61613.</para>
                </listitem>

                <listitem>
                    <para>
                         <emphasis>$options['driverOptions']['username'] = 'username';</emphasis>
                    </para>

                    <para>
                        Optional for some messaging servers. Read the manual
                        for your messaging server.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>$options['driverOptions']['password'] = 'password';</emphasis>
                    </para>

                    <para>
                        Optional for some messaging servers. Read the manual
                        for your messaging server.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>$options['driverOptions']['timeout_sec'] = 2;</emphasis>
                    </para>

                    <para>
                        <emphasis>$options['driverOptions']['timeout_usec'] = 0;</emphasis>
                    </para>

                    <para>
                        This is the amount of time that
                        <classname>Zend_Queue_Adapter_Activemq</classname> will wait for
                        read activity on a socket before returning no messages.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.queue.adapters.configuration.Db">
            <title>Db - Zend_Queue_Adapter_Db</title>

            <para>
                Driver options are checked for a few required options such
                as <emphasis>type</emphasis>, <emphasis>host</emphasis>,
                <emphasis>username</emphasis>, <emphasis>password</emphasis>,
                and <emphasis>dbname</emphasis>. You may pass along
                additional parameters for <methodname>Zend_DB::factory()</methodname> as parameters
                in <varname>$options['driverOptions']</varname>. An example of an additional
                option not listed here, but could be passed would be <emphasis>port</emphasis>.
            </para>

            <programlisting language="php"><![CDATA[
$options = array(
    'driverOptions' => array(
        'host'      => 'db1.domain.tld',
        'username'  => 'my_username',
        'password'  => 'my_password',
        'dbname'    => 'messaging',
        'type'      => 'pdo_mysql',
        'port'      => 3306, // optional parameter.
    ),
    'options' => array(
        // use Zend_Db_Select for update, not all databases can support this
        // feature.
        Zend_Db_Select::FOR_UPDATE => true
    )
);

// Create a database queue.
$queue = new Zend_Queue('Db', $options);
]]></programlisting>

            <itemizedlist>
                <listitem>
                    <para>
                         <emphasis>$options['name'] = 'queue1';</emphasis>
                    </para>

                    <para>
                        This is the name of the queue that you wish to start using. (Required)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>$options['driverOptions']['type'] = 'Pdo';</emphasis>
                    </para>

                    <para>
                        <emphasis>type</emphasis> is the adapter you wish to have
                        <methodname>Zend_Db::factory()</methodname> use. This is
                        the first parameter for the
                        <methodname>Zend_Db::factory()</methodname> class
                        method call.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>$options['driverOptions']['host'] = 'host.domain.tld';</emphasis>
                    </para>

                    <para>
                        <emphasis>$options['driverOptions']['host'] = '127.0.0.1';</emphasis>
                    </para>

                    <para>You may set host to an IP address or a hostname.</para>

                    <para>Default setting for host is '127.0.0.1'.</para>
                </listitem>

                <listitem>
                    <para>
                         <emphasis>$options['driverOptions']['username'] = 'username';</emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>$options['driverOptions']['password'] = 'password';</emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>$options['driverOptions']['dbname'] = 'dbname';</emphasis>
                    </para>

                    <para>
                        The database name that you have created the required tables for.
                        See the notes section below.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.queue.adapters.configuration.memcacheq">
            <title>MemcacheQ - Zend_Queue_Adapter_Memcacheq</title>

            <itemizedlist>
                <listitem>
                    <para>
                         <emphasis>$options['name'] = 'queue1';</emphasis>
                    </para>

                    <para>
                        This is the name of the queue that you wish to start using. (Required)
                    </para>
                </listitem>

                <listitem>
                    <para>
                         <emphasis>$options['driverOptions']['host'] = 'host.domain.tld';</emphasis>
                    </para>

                    <para>
                         <emphasis>$options['driverOptions']['host'] = '127.0.0.1;'</emphasis>
                    </para>

                    <para>You may set host to an IP address or a hostname.</para>

                    <para>Default setting for host is '127.0.0.1'.</para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>$options['driverOptions']['port'] = 22201;</emphasis>
                    </para>

                    <para>The default setting for port is 22201.</para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.queue.adapters.configuration.platformjq">
            <title>Zend Platform Job Queue - Zend_Queue_Adapter_PlatformJobQueue</title>

            <itemizedlist>
                <listitem>
                    <para>
                         <emphasis>$options['daemonOptions']['host'] = '127.0.0.1:10003';</emphasis>
                    </para>

                    <para>
                        The hostname and port corresponding to the Zend Platform Job Queue daemon
                        you will use. (Required)
                    </para>
                </listitem>

                <listitem>
                    <para>
                         <emphasis>$options['daemonOptions']['password'] = '1234';</emphasis>
                    </para>

                    <para>
                        The password required for accessing the Zend Platform Job Queue daemon.
                        (Required)
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.queue.adapters.configuration.array">
            <title>Array - Zend_Queue_Adapter_Array</title>

            <itemizedlist>
                <listitem>
                    <para>
                         <emphasis>$options['name'] = 'queue1';</emphasis>
                    </para>

                    <para>
                        This is the name of the queue that you wish to start using. (Required)
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>

    <sect2 id="zend.queue.adapters.notes">
        <title>Notes for Specific Adapters</title>

        <para>The following adapters have notes:</para>

        <sect3 id="zend.queue.adapters.notes.activemq">
            <title>Apache ActiveMQ</title>

            <para>
                Visibility duration for
                <classname>Zend_Queue_Adapter_Activemq</classname> is not
                available.
            </para>

            <para>
                While Apache's ActiveMQ will support multiple subscriptions, the
                <classname>Zend_Queue</classname> does not. You must create a
                new <classname>Zend_Queue</classname> object for each individual
                subscription.
            </para>

            <para>
                ActiveMQ queue/topic names must begin with one of:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <filename>/queue/</filename>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <filename>/topic/</filename>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <filename>/temp-queue/</filename>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <filename>/temp-topic/</filename>
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                For example: <filename>/queue/testing</filename>
            </para>

            <para>
                The following functions are not supported:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                         <methodname>create()</methodname> - create queue.
                         Calling this function will throw an exception.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>delete()</methodname> - delete queue.
                        Calling this function will throw an exception.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getQueues()</methodname> - list queues.
                        Calling this function will throw an exception.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.queue.adapters.notes.zend_db">
            <title>Zend_Db</title>

            <para>
                The database <emphasis>CREATE TABLE ( ... )</emphasis> <acronym>SQL</acronym>
                statement can be found in <filename>Zend/Queue/Adapter/Db/mysql.sql</filename>.
            </para>
        </sect3>

        <sect3 id="zend.queue.adapters.notes.memcacheQ">
            <title>MemcacheQ</title>

            <para>
                Memcache can be downloaded from <ulink
                    url="http://www.danga.com/memcached/">http://www.danga.com/memcached/</ulink>.
            </para>

            <para>
                MemcacheQ can be downloaded from <ulink
                    url="http://memcachedb.org/memcacheq/">http://memcachedb.org/memcacheq/</ulink>.
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>deleteMessage()</methodname> - Messages are deleted upon
                        reception from the queue. Calling this function would
                        have no effect. Calling this function will throw an
                        error.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>count()</methodname> or <methodname>count($adapter)</methodname>
                        - MemcacheQ does not support a method for counting the number of items in
                        a queue. Calling this function will throw an error.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.queue.adapters.notes.platformjq">
            <title>Zend Platform Job Queue</title>

            <para>
                Job Queue is a feature of Zend Platform's Enterprise Solution offering. It is not a
                traditional message queue, and instead allows you to queue a script to execute,
                along with the parameters you wish to pass to it. You can find out more about Job
                Queue <ulink url="http://www.zend.com/en/products/platform/">on the zend.com
                    website</ulink>.
            </para>

            <para>
                The following is a list of methods where this adapter's behavior diverges from the
                standard offerings:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>create()</methodname> - Zend Platform does not have the concept
                        of discrete queues; instead, it allows administrators to provide scripts for
                        processing jobs. Since adding new scripts is restricted to the
                        administration interface, this method simply throws an exception indicating
                        the action is forbidden.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>isExists()</methodname> - Just like
                        <methodname>create()</methodname>, since Job Queue does not have a notion of
                        named queues, this method throws an exception when invoked.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>delete()</methodname> - similar to
                        <methodname>create()</methodname>, deletion of JQ scripts is not possible
                        except via the admin interface; this method raises an exception.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getQueues()</methodname> - Zend Platform does not allow
                        introspection into the attached job handling scripts via the
                        <acronym>API</acronym>. This method throws an exception.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>count()</methodname> - returns the total number of jobs
                        currently active in the Job Queue.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>send()</methodname> - this method is perhaps the one method that
                        diverges most from other adapters. The <varname>$message</varname> argument
                        may be one of three possible types, and will operate differently based on
                        the value passed:
                    </para>

                    <itemizedlist>
                        <listitem>
                            <para>
                                <acronym>string</acronym> - the name of a script registered with Job
                                Queue to invoke. If passed in this way, no arguments are provided to
                                the script.
                            </para>
                        </listitem>

                        <listitem>
                            <para>
                                <acronym>array</acronym> - an array of values with which to
                                configure a <classname>ZendApi_Job</classname> object. These may
                                include the following:
                            </para>

                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>script</varname> - the name of the Job Queue script
                                        to invoke. (Required)
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>priority</varname> - the job priority to use when
                                        registering with the queue.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>name</varname> - a short string describing the job.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>predecessor</varname> - the ID of a job on which
                                        this one depends, and which must be executed before this one
                                        may begin.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>preserved</varname> - whether or not to retain the
                                        job within the Job Queue history. By default, off; pass a
                                        <constant>TRUE</constant> value to retain it.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>user_variables</varname> - an associative array of
                                        all variables you wish to have in scope during job execution
                                        (similar to named arguments).
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>interval</varname> - how often, in seconds, the job
                                        should run. By default, this is set to 0, indicating it
                                        should run once, and once only.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>end_time</varname> - an expiry time, past which the
                                        job should not run. If the job was set to run only once,
                                        and <varname>end_time</varname> has passed, then the job
                                        will not be executed. If the job was set to run on an
                                        interval, it will not execute again once
                                        <varname>end_time</varname> has passed.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>schedule_time</varname> - a <acronym>UNIX</acronym>
                                        timestamp indicating when to run the job; by default, 0,
                                        indicating the job should run as soon as possible.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>application_id</varname> - the application
                                        identifier of the job. By default, this is
                                        <constant>NULL</constant>, indicating that one will be
                                        automatically assigned by the queue, if the queue was
                                        assigned an application ID.
                                    </para>
                                </listitem>
                            </itemizedlist>

                            <para>
                                As noted, only the <varname>script</varname> argument is required;
                                all others are simply available to allow passing more fine-grained
                                detail on how and when to run the job.
                            </para>
                        </listitem>

                        <listitem>
                            <para>
                                <classname>ZendApi_Job</classname> - finally, you may simply pass a
                                <classname>ZendApi_Job</classname> instance, and it will be passed
                                along to Platform's Job Queue.
                            </para>
                        </listitem>
                    </itemizedlist>

                    <para>
                        In all instances, <methodname>send()</methodname> returns a
                        <classname>Zend_Queue_Message_PlatformJob</classname> object, which provides
                        access to the <classname>ZendApi_Job</classname> object used to communicate
                        with Job Queue.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>receive()</methodname> - retrieves a list of active jobs from
                        Job Queue. Each job in the returned set will be an instance of
                        <classname>Zend_Queue_Message_PlatformJob</classname>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>deleteMessage()</methodname> - since this adapter only works
                        with Job Queue, this method expects the provided <varname>$message</varname>
                        to be a <classname>Zend_Queue_Message_PlatformJob</classname> instance, and
                        will throw an exception otherwise.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.queue.adapters.notes.array">
            <title>Array (local)</title>

            <para>
                The Array queue is a <acronym>PHP</acronym> <methodname>array()</methodname>
                in local memory. The <classname>Zend_Queue_Adapter_Array</classname> is good for
                unit testing.
            </para>
        </sect3>
    </sect2>
</sect1>