<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.search.lucene.advanced">
    <title>Erweitert</title>

    <sect2 id="zend.search.lucene.advanced.format_migration">
        <title>Beginnend mit 1.6, Behandlung von Index Format Veränderungen</title>

        <para>
            Die <classname>Zend_Search_Lucene</classname> Komponente arbeitet mit den Index Formaten
            der Java Lucene Version 1.4-1.9, 2.1 und 2.3.
        </para>

        <para>
            Das aktuelle Indexformat kann durch den Aufruf von
            <code>$index->getFormatVersion()</code> abgefragt werden. Er gibt eine der folgenden
             Werte zurück:

            <itemizedlist>
                <listitem>
                    <para>
                        <constant>Zend_Search_Lucene::FORMAT_PRE_2_1</constant> für das Java
                        Lucene Index Format 1.4-1.9.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Zend_Search_Lucene::FORMAT_2_1</constant> für das Java Lucene
                        Index Format 2.1 (es wird auch in Lucene 2.2 verwendet).
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Zend_Search_Lucene::FORMAT_2_3</constant> für das Java Lucene
                        Index Format 2.3.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <para>
            Indexveränderungen werden <emphasis>nur</emphasis> durchgeführt wenn irgendein
            Update des Index durchgeführt wird. Das passiert wenn ein neues Dokument zu einem Index
            hinzugefügt wird, oder wenn manuell eine Indexoptimierung durch den Aufruf von
            <code>$index->optimize()</code> gestartet wird.
        </para>

        <para>
            In solch einem Fall kann <classname>Zend_Search_Lucene</classname> den Index in eine
            höhere Formatversion konvertieren. Das geschieht <emphasis>immer</emphasis> für Indezes
            welche im <constant>Zend_Search_Lucene::FORMAT_PRE_2_1</constant> sind. Diese werden
            automatisch ins Format 2.1 konvertiert.
        </para>

        <para>
            Man kann den Konvertierungsprozess managen und Ziel-Indexformate durch
            <code>$index->setFormatVersion()</code> zuweisen welches entweder die
            <constant>Zend_Search_Lucene::FORMAT_2_1</constant> oder
            <constant>Zend_Search_Lucene::FORMAT_2_3</constant> Konstante entgegennimmt:

            <itemizedlist>
                <listitem>
                    <para>
                        <constant>Zend_Search_Lucene::FORMAT_2_1</constant> macht eigentlich gar
                        nichts da pre-2.1 Indezes automatisch in das 2.1 Format konvertiert werden.
                    </para>
                </listitem>

                <listitem>
                    <para>
                         <constant>Zend_Search_Lucene::FORMAT_2_3</constant> erzwingt die
                         Konvertierung ins 2.3 Format.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <para>
            Rückwärts Konvertierungen werden nicht unterstützt.
        </para>

        <note>
            <title>Wichtig!</title>

            <para>
                Sobald Indezes in eine höhere Version konvertiert wurden können Sie nicht zurück
                konvertiert werden. Deswegen sollte man ein Backup der Indezes machen wenn man plant
                zu einer höheren Version zu migrieren, man aber die Möglichkeit haben will wieder
                zurückzugehen.
            </para>
        </note>

    </sect2>

    <sect2 id="zend.search.lucene.advanced.static">
        <title>Den Index als statische Eigenschaft verwenden</title>

        <para>
            Das <classname>Zend_Search_Lucene</classname> Objekt verwendet einen Objekt Destruktor
            um Änderungen mitzuteilen und um Ressourcen zu löschen.
        </para>

        <para>
            Es speichert hinzugefügte Dokumente im Speicher und speichert neu indizierte Segmente
            auf die Platte abhängig vom <code>MaxBufferedDocs</code> Parameter.
        </para>

        <para>
            Wenn das <code>MaxBufferedDocs</code> Limit nicht erreicht wird, gibt es einige
            "ungespeicherte" Dokumente welche als neue Segmente in der Destruktor Methode des
            Objektes gespeichert werden. Die automatische Optimierungsprozedur des Index wird
            aufgerufen wenn das notwendig wird, abhängig von den <code>MaxBufferedDocs</code>,
            <code>MaxMergeDocs</code> und <code>MergeFactor</code> Parametern.
        </para>

        <para>
            Statische Objekteigenschaften (siehe anbei) werden <emphasis>nach</emphasis> der letzten
            Zeile des ausgeführten Skripts vernichtet.
        </para>

        <programlisting language="php"><![CDATA[
class Searcher {
    private static $_index;

    public static function initIndex() {
        self::$_index = Zend_Search_Lucene::open('path/to/index');
    }
}

Searcher::initIndex();
]]></programlisting>

        <para>
            Auf die gleiche Art und Weise wird der Objektdestruktor für statische Eigenschaften an
            dieser Stelle des Programablaufes korrekt aufgerufen.
        </para>

        <para>
            Ein potentielles Problem ist die Behandlung von Ausnahmen. Ausnahmen die vom Destruktor
            eines statischen Objekts geworfen werden haben keinen Inhalt, weil der Destruktor
            ausgeführt wird nachdem das Skript bereits beendet wurde.
        </para>

        <para>
            Man kann in solchen Fällen eine "Fatal error: Exception thrown without a stack frame in
            Unknown on line 0" Fehlermeldung statt der Beschreibung einer Ausnahme sehen.
        </para>

        <para>
            <classname>Zend_Search_Lucene</classname> bietet einen Workaround zu diesem Problem, mit
            der <methodname>commit()</methodname> Methode, an. Diese speichert alle ungespeicherten
            Änderungen und leert den Speicher der für das Speichern der neuen Segmente verwendet
            wird. Man kann die commit Operation jederzeit oder auch mehrmals während der Ausführung
            des Skripts anwenden. Man kann das <classname>Zend_Search_Lucene</classname> Objekt
            trotzdem für das suchen, hinzufügen oder löschen von Dokumenten nach der commit
            Operation verwenden. Aber der Aufruf von <methodname>commit()</methodname> garantiert,
            das wenn nach dem Aufruf von <methodname>commit()</methodname> keine Dokumente
            hinzugefügt oder gelöscht werden, der Destruktor von
            <classname>Zend_Search_Lucene</classname> nichts zu tun hat, und er deswegen keine
            Ausnahme wirft:
        </para>

        <programlisting language="php"><![CDATA[
class Searcher {
    private static $_index;

    public static function initIndex() {
        self::$_index = Zend_Search_Lucene::open('path/to/index');
    }

    ...

    public static function commit() {
        self::$_index->commit();
    }
}

Searcher::initIndex();

...

// Sktipt Shutdorn Routine
...
Searcher::commit();
...
]]></programlisting>
    </sect2>
</sect1>
