<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15157 -->
<!-- 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>
                        <classname>Zend_Search_Lucene::FORMAT_PRE_2_1</classname> für das Java Lucene Index Format 1.4-1.9.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <classname>Zend_Search_Lucene::FORMAT_2_1</classname> für das Java Lucene Index Format 2.1
                        (es wird auch in Lucene 2.2 verwendet).
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <classname>Zend_Search_Lucene::FORMAT_2_3</classname> 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
            <classname>Zend_Search_Lucene::FORMAT_PRE_2_1</classname> 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
            <classname>Zend_Search_Lucene::FORMAT_2_1</classname> oder <classname>Zend_Search_Lucene::FORMAT_2_3</classname>
            Konstante entgegennimmt:
            <itemizedlist>
                <listitem>
                    <para>
                        <classname>Zend_Search_Lucene::FORMAT_2_1</classname> macht eigentlich gar nichts da
                        pre-2.1 Indezes automatisch in das 2.1 Format konvertiert werden.
                    </para>
                </listitem>
                <listitem>
                    <para>
                         <classname>Zend_Search_Lucene::FORMAT_2_3</classname> 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.

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

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

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


        <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 <code>commit()</code> 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 <code>commit()</code> garantiert, das wenn nach dem Aufruf von <code>commit()</code>
            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:

            <programlisting role="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>
        </para>

    </sect2>
</sect1>