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

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

    <para>
        <classname>Zend_Queue</classname> unterstützt alle Queues die das Interface
        <classname>Zend_Queue_Adapter_AdapterInterface</classname> implementieren. Die folgenden
        Nachrichten Queue Services werden unterstützt:
    </para>

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

        <listitem>
            <para>Eine Datenbank verwendende Queue über <classname>Zend_Db</classname>.</para>
        </listitem>

        <listitem>
            <para>
                Eine <ulink url="http://memcachedb.org/memcacheq/">MemcacheQ</ulink> verwendende
                Queue über <classname>Memcache</classname>.
            </para>
        </listitem>

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

        <listitem>
            <para>Ein lokales Array. Nützlich für Unit Tests.</para>
        </listitem>
    </itemizedlist>

    <note id="zend.queue.adapters.limitations">
        <title>Einschränkungen</title>

        <para>
            Das Transaction Handling für Nachrichten wird nicht unterstützt.
        </para>
    </note>

    <sect2 id="zend.queue.adapters.configuration">
        <title>Spezielle Adapter - Konfigurations Optionen</title>

        <para>
            Wenn eine Standardeinstellung angezeigt wird, dann ist der Parameter optional.
            Wenn keine Standardeinstellung spezifiziert ist dann wird der Parameter benötigt.
        </para>

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

            <para>
                Hier aufgeführte Optionen sind bekannte Notwendigkeiten. Nicht alle Nachrichten
                Server benötigen username oder password.
            </para>

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

                    <para>
                        Das ist der Name der Queue die man anfangen will zu verwenden. (Benötigt)
                    </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>
                        Man kann host auf eine IP Adresse oder einen Hostnamen setzen.
                    </para>

                    <para>
                        Der Standardwert für host ist '127.0.0.1'.
                    </para>
                </listitem>

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

                    <para>Die Standardeinstellung für port ist 61613.</para>
                </listitem>

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

                    <para>
                        Optional für einige Nachrichten Server. Lesen Sie das Handbuch für Ihren
                        Nachrichten Server.
                    </para>
                </listitem>

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

                    <para>
                        Optional für einige Nachrichten Server. Lesen Sie das Handbuch für Ihren
                        Nachrichten Server.
                    </para>
                </listitem>

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

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

                    <para>
                        Das ist die Menge an Zeit die
                        <classname>Zend_Queue_Adapter_Activemq</classname> für einen Lesezugriff
                        auf einem Socket wartet bevor keine Nachricht zurückgegeben wird.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

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

            <para>
                Optionen des Treibers werden für wenige benötigte Optionen geprüft so wie
                <emphasis>type</emphasis>, <emphasis>host</emphasis>,
                <emphasis>username</emphasis>, <emphasis>password</emphasis> und
                <emphasis>dbname</emphasis>. Man kann zusätzliche Parameter für
                <methodname>Zend_DB::factory()</methodname> als Paramerter in
                <varname>$options['driverOptions']</varname> übergeben. Ein Beispiel für eine
                zusätzliche Option die hier nicht aufgeführt ist, aber übergeben werden könnte ist
                <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, // Optionaler Parameter
    ),
    'options' => array(
        // Verwenden von Zend_Db_Select für das Update, nicht alle Datenbanken
        // unterstützen dieses Feature.
        Zend_Db_Select::FOR_UPDATE => true
    )
);

// Eine Datenbank Queue erstellen.
$queue = new Zend_Queue('Db', $options);
]]></programlisting>

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

                    <para>
                        Das ist der Name der Queue die man anfangen will zu verwenden. (Benötigt)
                    </para>
                </listitem>

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

                    <para>
                        <emphasis>type</emphasis> ist der Adapter von dem man will das Ihn
                        <methodname>Zend_Db::factory()</methodname> verwendet. Das ist der erste
                        Parameter für den Aufruf der Klassenmethode
                        <methodname>Zend_Db::factory()</methodname>
                    </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>
                        Man kann host auf eine IP Adresse oder einen Hostnamen setzen.
                    </para>

                    <para>
                        Der Standardwert für host ist '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>
                        Der Name der Datenbank für die man die benötigten Tabellen erstellt hat.
                        Siehe das unten stehende Notizen Kapitel.
                    </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>
                        Das ist der Name der Queue die man anfangen will zu verwenden. (Benötigt)
                    </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>
                        Man kann host auf eine IP Adresse oder einen Hostnamen setzen.
                    </para>

                    <para>
                        Der Standardwert für host ist '127.0.0.1'.
                    </para>
                </listitem>

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

                    <para>Die Standardeinstellung für port ist 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>
                        Hostname und Port die mit dem Daemon der Zend Platform Job Queue
                        korrespondieren, die man verwenden will. (Benötigt)
                    </para>
                </listitem>

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

                    <para>
                        Das Passwort welches für den Zugriff auf den Daemon der Zend Platform Job
                        Queue benötigt wird. (Benötigt)
                    </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>
                        Das ist der Name der Queue die man anfangen will zu verwenden. (Benötigt)
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>

    <sect2 id="zend.queue.adapters.notes">
        <title>Hinweise für spezielle Adapter</title>
        <para>Die folgenden Adapter haben Hinweise:</para>

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

            <para>
                Die Dauer der Sichtbarkeit (visibility duration) ist für
                <classname>Zend_Queue_Adapter_Activemq</classname> nicht vorhanden.
            </para>

            <para>
                Wärend Apache's ActiveMQ mehrere Einschreibungen unterstützt, wird das von
                <classname>Zend_Queue</classname> nicht unterstützt. Man muss ein neues
                <classname>Zend_Queue</classname> Objekt für jede individuelle Einschreibung
                erstellen.
            </para>

            <para>
                ActiveMQ Queue oder Topic Namen müssen mit einem der folgenden beginnen:
            </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>
                Zum Beispiel: <filename>/queue/testing</filename>
            </para>

            <para>
                Die folgenden Funktionen werden nicht unterstützt:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                         <methodname>create()</methodname> - Erstellt eine Queue. Der Aufruf dieser
                         Funktion wird eine Exception werfen.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>delete()</methodname> - Löscht eine Queue. Der Aufruf dieser
                        Funktion wird eine Exception werfen.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getQueues()</methodname> - Auflisten von Queues. Der Aufruf
                        dieser Funktion wird eine Exception werden.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

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

            <para>
                Das Datenbank <acronym>SQL</acronym> Statement
                <emphasis>CREATE TABLE ( ... )</emphasis> kann in
                <filename>Zend/Queue/Adapter/Db/mysql.sql</filename> gefunden werden.
            </para>
        </sect3>

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

            <para>
                Memcache kann von <ulink
                    url="http://www.danga.com/memcached/">http://www.danga.com/memcached/</ulink>
                heruntergeladen werden.
            </para>

            <para>
                MemcacheQ kann von <ulink
                    url="http://memcachedb.org/memcacheq/">http://memcachedb.org/memcacheq/</ulink>
                heruntergeladen werden.
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>deleteMessage()</methodname> - Nachrichten werden von der Queue
                        gelöscht nachdem Sie von der Queue empfangen werden. Der Aufruf dieser
                        Funktion hätte keinen Effekt. Der Aufruf dieser Funktion wird keinen Fehler
                        werfen.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>count()</methodname> oder
                        <methodname>count($adapter)</methodname> - MemcacheQ unterstützt keine
                        Methode für das Zählen der Anzahl an Elementen in einer Queue. Der Aufruf
                        dieser Funktion wird keinen Fehler werfen.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

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

            <para>
                Job Queue ist ein Feature das von Zend Platform's Enterprise Solution angeboten
                wird. Es ist keine traditionelle Nachrichten Queue, sondern erlaubt es ein Skript
                zu queuen um es auszuführen, zusammen mit den Parametern die man an dieses
                übergeben will. Man kann mehr über die Job Queue <ulink
                    url="http://www.zend.com/en/products/platform/">auf der Webseite von
                    zend.com</ulink> herausfinden.
            </para>

            <para>
                Nachfolgend ist eine Liste von Methoden bei denen sich das Verhalten dieses
                Adapters vom Standardverhalten unterscheidet:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>create()</methodname> - Zend Platform hat kein Konzept von
                        diskreten Queues; stattdessen erlaubt es Administratoren Skripte für die
                        Bearbeitung der Queue anzugeben. Da das hinzufügen von neuen Skripten auf
                        das Administrations Interface begrenzt ist, wirft diese Methode einfach
                        eine Exception um anzuzeigen das diese Aktion verboten ist.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>isExists()</methodname> - Genauso wie
                        <methodname>create()</methodname>, und da die Job Queue keine Notation für
                        benannte Queues hat wirft diese Methode eine Exception wenn Sie aufgerufen
                        wird.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>delete()</methodname> - Ähnlich wie
                        <methodname>create()</methodname>, ist das Löschen von JQ Skripten nicht
                        möglich, ausser über das Admin Interface; diese Methode wirft eine
                        Exception.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getQueues()</methodname> - Zend Platform erlaubt es nicht
                        über die <acronym>API</acronym> die angehängten Job Handling Skripte
                        einzusehen. Diese Methode wirft eine Exception.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>count()</methodname> - Gibt die totale Anzahl an Jobs zurück
                        die aktuell in der Job Queue aktiv sind.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>send()</methodname> - Diese Methode ist möglicherweise die eine
                        Methode welche sich am meisten von den anderen Adaptern unterscheidet.
                        Das <varname>$message</varname> Argument kann eine von drei möglichen
                        Typen sein und arbeitet unterschiedlich, basierend auf dem übergebenen
                        Wert:
                    </para>

                    <itemizedlist>
                        <listitem>
                            <para>
                                <acronym>string</acronym> - Der Name eines betroffenen Skripts das
                                in der Job Queue registriert ist. Wenn es auf diesem Weg übergeben
                                wird, werden keine Argumente an das Skript übergeben.
                            </para>
                        </listitem>

                        <listitem>
                            <para>
                                <acronym>array</acronym> - Ein Array von Werte mit denen ein
                                <classname>ZendApi_Job</classname> Objekt konfiguriert werden soll.
                                Dieses kann folgendes enthalten:
                            </para>

                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>script</varname> - Den Namen des betroffenen
                                        Job Queue Skripts. (Benötigt)
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>priority</varname> - Die Priorität des Jobs die
                                        verwendet werden soll wenn er in der Queue registriert
                                        wird.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>name</varname> - Ein kurzer String der den Job
                                        beschreibt.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>predecessor</varname> - Die ID eines Jobs von der
                                        dieser abhängt, und welches aufgeführt werden muß bevor
                                        dieses anfangen kann.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>preserved</varname> - Ob der Job in der History
                                        der Job Queue behalten werden soll. Standardmäßig aus;
                                        wenn ein <constant>TRUE</constant> Wert übergeben wird,
                                        dann wird er behalten.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>user_variables</varname> - Ein Assoziatives Array
                                        aller Variablen die man während der Ausführung des Jobs im
                                        Geltungsbereich haben will (ähnlich benannten Argumenten).
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>interval</varname> - Wie oft, in Sekunden, der Job
                                        ausgeführt werden soll. Standardmäßig ist das auf 0
                                        gesetzt, was anzeigt das er einmal, und nur einmal
                                        ausgeführt werden soll.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>end_time</varname> - Eine abgelaufene Zeit, nach
                                        welcher der Job nicht ausgeführt werden soll. Wenn der Job
                                        so gesetzt wurde das er nur einmal ausgeführt wird, und
                                        <varname>end_time</varname> übergeben wurde, dann wird der
                                        Job nicht ausgeführt. Wenn der Job so gesetzt wurde das er
                                        in einem Intervall ausgeführt wird, das wird er nicht mehr
                                        ausgeführt bis <varname>end_time</varname> abgelaufen ist.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>schedule_time</varname> - Ein
                                        <acronym>UNIX</acronym> Zeitstempel der anzeigt wann der
                                        Job ausgeführt werden soll; standardmäßig 0, was anzeigt
                                        das der Job so früh wie möglich ausgeführt werden soll.
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>application_id</varname> - Der Identifikator der
                                        Anwendung für den Job. Standardmäßig ist er
                                        <constant>NULL</constant>, was anzeigt das automatisch
                                        einer von der Queue zugeordnet wird, wenn die Queue einer
                                        Anwendungs ID zugeordnet wird.
                                    </para>
                                </listitem>
                            </itemizedlist>

                            <para>
                                Wie erwähnt, wird nur das <varname>script</varname> Argument
                                benötigt; alle anderen anderen nur nur einfach vorhanden um es zu
                                erlauben feinkörnigere Details darüber zu übergeben, wie und wann
                                ein Job ausgeführt werden soll.
                            </para>
                        </listitem>

                        <listitem>
                            <para>
                                <classname>ZendApi_Job</classname> - Letztendlich kann einfach eine
                                Instanz von <classname>ZendApi_Job</classname> übergeben werden und
                                Sie wird zur Job Queue der Plattform übergeben.
                            </para>
                        </listitem>
                    </itemizedlist>

                    <para>
                        In allen Instanzen gibt <methodname>send()</methodname> ein
                        <classname>Zend_Queue_Message_PlatformJob</classname> Objekt zurück,
                        welches Zugriff zum <classname>ZendApi_Job</classname> Objekt gibt und
                        verwendet wird um mit der Job Queue zu kommunizieren.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>receive()</methodname> - Empfängt eine Liste von aktiven Jobs
                        von der Job Queue. Jeder Job im zurückgegebenen Set ist eine Instanz von
                        <classname>Zend_Queue_Message_PlatformJob</classname>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>deleteMessage()</methodname> - Da dieser Adapter nur mit der
                        Job Queue arbeitet, erwartet diese Methode das die übergebene
                        <varname>$message</varname> eine Instanz von
                        <classname>Zend_Queue_Message_PlatformJob</classname> ist, und wirft
                        andernfalls eine Exception.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

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

            <para>
                Die Array Queue ist ein <acronym>PHP</acronym> <methodname>array()</methodname>
                im lokalen Speicher. <classname>Zend_Queue_Adapter_Array</classname> ist gut
                für das Unit Testen.
            </para>
        </sect3>
    </sect2>
</sect1>