repo_zf1/documentation/manual/de/module_specs/Zend_Search_Lucene-Extending.xml

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

    <sect2 id="zend.search.lucene.extending.analysis">
        <title>Textanalyse</title>

        <para>
            Die <classname>Zend_Search_Lucene_Analysis_Analyzer</classname> Klasse wird vom Indexer
            verwendet, um die Textfelder der Dokumente in Abschnitte aufzuteilen.
        </para>

        <para>
            Die <methodname>Zend_Search_Lucene_Analysis_Analyzer::getDefault()</methodname> und
            <methodname>Zend_Search_Lucene_Analysis_Analyzer::setDefault()</methodname> Methoden
            werden verwendet, um den Standardanalysator zu bekommen oder festzulegen.
        </para>

        <para>
            Man kann einen eigenen Textanalysator zuordnen oder ihn aus den vordefinierten
            Analysatoren auswählen:
            <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Text</classname> und
            <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Text_CaseInsensitive</classname>
            (Standard). Beide interpretieren einen Abschnitt als eine Sequenz aus Buchstaben.
            <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Text_CaseInsensitive</classname>
            konvertiert alle Abschnitte in Kleinbuchstaben.
        </para>

        <para>
            Um zwischen Analysatoren zu wechseln:
        </para>

        <programlisting language="php"><![CDATA[
Zend_Search_Lucene_Analysis_Analyzer::setDefault(
    new Zend_Search_Lucene_Analysis_Analyzer_Common_Text());
...
$index->addDocument($doc);
]]></programlisting>

        <para>
            Die <classname>Zend_Search_Lucene_Analysis_Analyzer_Common</classname> Klasse wurde als
            Anker für alle benutzerdefinierten Analysatoren entwickelt. Benutzer sollten nur die
            <methodname>reset()</methodname> und <methodname>nextToken()</methodname> Methoden
            definieren, welche ihren String von der $_input Eigenschaft nimmt und die Abschnitte
            Stück für Stück zurückgibt (ein <constant>NULL</constant> Wert indiziert das Ende des
            Streams).
        </para>

        <para>
            Die <methodname>nextToken()</methodname> Methode sollte die
            <methodname>normalize()</methodname> Methode auf jedem Token aufrufen. Das erlaubt die
            Verwendung von Abschnittsfiltern im eigenen Analysator.
        </para>

        <para>
            Hier ist ein Beispiel für einen eigenen Analysator, welcher Wörter mit Ziffern als
            Begriffe akzeptiert:

            <example id="zend.search.lucene.extending.analysis.example-1">
                <title>Eigener Textanalysator</title>

                <programlisting language="php"><![CDATA[
/**
 * Hier ist ein eigener Textanalysator, der Worte mit Ziffern
 * als einen Begriff behandelt
 */

class My_Analyzer extends Zend_Search_Lucene_Analysis_Analyzer_Common
{
    private $_position;

    /**
     * Setzt den Token Stream zurück
     */
    public function reset()
    {
        $this->_position = 0;
    }

    /**
     * Tokenization stream API
     * Get next token
     * Returns null at the end of stream
     *
     * @return Zend_Search_Lucene_Analysis_Token|null
     */
    public function nextToken()
    {
        if ($this->_input === null) {
            return null;
        }

        while ($this->_position < strlen($this->_input)) {
            // skip white space
            while ($this->_position < strlen($this->_input) &&
                   !ctype_alnum( $this->_input[$this->_position] )) {
                $this->_position++;
            }

            $termStartPosition = $this->_position;

            // read token
            while ($this->_position < strlen($this->_input) &&
                   ctype_alnum( $this->_input[$this->_position] )) {
                $this->_position++;
            }

            // Empty token, end of stream.
            if ($this->_position == $termStartPosition) {
                return null;
            }

            $token = new Zend_Search_Lucene_Analysis_Token(
                                      substr($this->_input,
                                             $termStartPosition,
                                             $this->_position -
                                             $termStartPosition),
                                      $termStartPosition,
                                      $this->_position);
            $token = $this->normalize($token);
            if ($token !== null) {
                return $token;
            }
            // Continue if token is skipped
        }

        return null;
    }
}

Zend_Search_Lucene_Analysis_Analyzer::setDefault(
    new My_Analyzer());
]]></programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.extending.filters">
        <title>Filtern von Tokens</title>

        <para>
            Der <classname>Zend_Search_Lucene_Analysis_Analyzer_Common</classname> Analisator bietet
            auch einen Mechanismus zum Filtern von Tokens.
        </para>

        <para>
            Die <classname>Zend_Search_Lucene_Analysis_TokenFilter</classname> Klasse bietet ein
            abstraktes Interface für solche Filter. Eigene Filter sollten diese Klasse direkt oder
            indirekt erweitern.
        </para>

        <para>
            Alle eigenen Filter müssen die <methodname>normalize()</methodname> Methode
            implementieren, welche den Eingabe Token verändern oder signalisieren, dass der Token
            übersprungen werden sollte.
        </para>

        <para>
            Es gibt bereits drei Filter die im Analyse Unterpaket definierte sind:

            <itemizedlist>
                <listitem>
                    <para>
                        <classname>Zend_Search_Lucene_Analysis_TokenFilter_LowerCase</classname>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>Zend_Search_Lucene_Analysis_TokenFilter_ShortWords</classname>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>Zend_Search_Lucene_Analysis_TokenFilter_StopWords</classname>
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <para>
            Der <code>LowerCase</code> Filter wird bereits standardmäßig für den
            <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Text_CaseInsensitive</classname>
            Analysator verwendet.
        </para>

        <para>
            Die <code>ShortWords</code> und <code>StopWords</code> Filter können mit bereits
            definierten oder eigenen Analysatoren wie folgt verwendet werden:
        </para>

        <programlisting language="php"><![CDATA[
$stopWords = array('a', 'an', 'at', 'the', 'and', 'or', 'is', 'am');
$stopWordsFilter =
    new Zend_Search_Lucene_Analysis_TokenFilter_StopWords($stopWords);

$analyzer =
    new Zend_Search_Lucene_Analysis_Analyzer_Common_TextNum_CaseInsensitive();
$analyzer->addFilter($stopWordsFilter);

Zend_Search_Lucene_Analysis_Analyzer::setDefault($analyzer);
]]></programlisting>

        <programlisting language="php"><![CDATA[
$shortWordsFilter = new Zend_Search_Lucene_Analysis_TokenFilter_ShortWords();

$analyzer =
    new Zend_Search_Lucene_Analysis_Analyzer_Common_TextNum_CaseInsensitive();
$analyzer->addFilter($shortWordsFilter);

Zend_Search_Lucene_Analysis_Analyzer::setDefault($analyzer);
]]></programlisting>

        <para>
            Der <classname>Zend_Search_Lucene_Analysis_TokenFilter_StopWords</classname> Konstruktor
            nimmt ein Array mit Stopwörtern als Eingabe entgegen. Aber Stopwörter können auch aus
            einer Datei geladen werden:
        </para>

        <programlisting language="php"><![CDATA[
$stopWordsFilter = new Zend_Search_Lucene_Analysis_TokenFilter_StopWords();
$stopWordsFilter->loadFromFile($my_stopwords_file);

$analyzer =
    new Zend_Search_Lucene_Analysis_Analyzer_Common_TextNum_CaseInsensitive();
$analyzer->addFilter($stopWordsFilter);

Zend_Search_Lucene_Analysis_Analyzer::setDefault($analyzer);
]]></programlisting>

        <para>
            Die Datei sollte eine normale Textdatei mit einem Wort pro Zeile sein. Das '#' Zeichen
            markiert eine Zeile als Kommentar.
        </para>

        <para>
            Der <classname>Zend_Search_Lucene_Analysis_TokenFilter_ShortWords</classname>
            Konstruktor hat ein optionales Argument. Es ist das Limit für die Wortlänge, der
            standardmäßig 2 ist.
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.extending.scoring">
        <title>Algorithmen für Punktwertermittlung</title>

        <para>
            Der Punktwert einer Abfrage <literal>q</literal> für das Dokument <literal>d</literal>
            ist wie folgt definiert:
        </para>

        <para>
            <code>score(q,d) = sum( tf(t in d) * idf(t) * getBoost(t.field in d) *
            lengthNorm(t.field in d) ) * coord(q,d) * queryNorm(q)</code>
        </para>

        <para>
            tf(t in d) - <methodname>Zend_Search_Lucene_Search_Similarity::tf($freq)</methodname> -
            ein Punktwertfaktor, der auf der Häufigkeit des Begriffes oder der Phrase innerhalb des
            Dokuments basiert.
        </para>

        <para>
            idf(t) -
            <methodname>Zend_Search_Lucene_Search_Similarity::idf($input, $reader)</methodname>
            - ein Punktwertfaktor für einen einfachen Begriff mit dem spezifischen Index.
        </para>

        <para>
            getBoost(t.field in d) - der Verstärkungsfaktor für das Begriffsfeld.
        </para>

        <para>
            lengthNorm($term) - der Normalisierungswert für ein Feld, der die Gesamtzahl der
            Begriffe innerhalb eines Fields enthält. Dieser Wert wird im Index abgelegt. Diese Wert
            werden zusammen mit dem Verstärkungsfaktor im Index abgelegt und vom Suchcode für
            alle Treffer eines Feldes zu Punktwerten multipliziert.
        </para>

        <para>
            Treffer in längeren Feldern sind weniger präzise, so dass Implementierungen dieser
            Methode normalerweise kleinere Werte zurückgeben, wenn numTokens groß ist, und größere
            Werte, wenn numTokens klein ist.
        </para>

        <para>
            coord(q,d) - <methodname>Zend_Search_Lucene_Search_Similarity::coord($overlap,
                $maxOverlap)</methodname> - ein Punktwertfaktor, der auf dem Anteil aller
            Abfragebegriffe basiert, die ein Dokument enthält.
        </para>

        <para>
            Das Vorhandensein eines grossen Teils der Abfragebegriffe gibt einen besseren Treffer
            für die Abfrage an, so dass Implementierungen dieser Methode normalerweise größere
            Werte zurückgeben, wenn das Verhältnis zwischen diesen Parametern groß ist, und kleinere
            Werte, wenn es klein ist.
        </para>

        <para>
            queryNorm(q) - der Normalisierungswert für eine Abfrage, welcher die Summe der
            quadrierten Gewichtungen jedes Begriffes eine Abfrage enthält. Dieser Wert wird für das
            Gewicht jedes Abfragebegriffes multipliziert.
            term.
        </para>

        <para>
            Dieses wirkt sich nicht auf die Reihenfolge ist, versucht aber, die Punktwerte
            für verschiedenen Abfragen vergleichbar zu machen.
        </para>

        <para>
            Der Algorithmen für die Punktwertermittlung kann durch die Definition einer eigenen
            Ähnlichkeitsklasse angepasst werden. Hierfür muss die
            <classname>Zend_Search_Lucene_Search_Similarity</classname> Klasse wie unten angegeben
            erweitert und anschließend die
            <methodname>Zend_Search_Lucene_Search_Similarity::setDefault($similarity);</methodname>
            Methode verwendet werden um Sie als Standard zu setzen.
        </para>

        <programlisting language="php"><![CDATA[
class MySimilarity extends Zend_Search_Lucene_Search_Similarity {
    public function lengthNorm($fieldName, $numTerms) {
        return 1.0/sqrt($numTerms);
    }

    public function queryNorm($sumOfSquaredWeights) {
        return 1.0/sqrt($sumOfSquaredWeights);
    }

    public function tf($freq) {
        return sqrt($freq);
    }

    /**
     * Es wird jetzt nicht verwendet. Berechnet den Wert eines Treffers
     * für eine ungenauen Phrasenanfrage.
     */
    public function sloppyFreq($distance) {
        return 1.0;
    }

    public function idfFreq($docFreq, $numDocs) {
        return log($numDocs/(float)($docFreq+1)) + 1.0;
    }

    public function coord($overlap, $maxOverlap) {
        return $overlap/(float)$maxOverlap;
    }
}

$mySimilarity = new MySimilarity();
Zend_Search_Lucene_Search_Similarity::setDefault($mySimilarity);
]]></programlisting>
    </sect2>

    <sect2 id="zend.search.lucene.extending.storage">
        <title>Storage Container</title>

        <para>
            Die abstrakte Klasse <classname>Zend_Search_Lucene_Storage_Directory</classname>
            definiert Funktionalitäten für Verzeichnisse.
        </para>

        <para>
            Der <classname>Zend_Search_Lucene</classname> Konstruktur verwendet als Eingabe entweder
            einen String oder ein <classname>Zend_Search_Lucene_Storage_Directory</classname>
            Objekt.
        </para>

        <para>
            Die <classname>Zend_Search_Lucene_Storage_Directory_Filesystem</classname> Klasse
            implementiert Verzeichnisfunktionalitäten für ein Dateisystem.
        </para>

        <para>
            Wenn ein String als Eingabe für den <classname>Zend_Search_Lucene</classname>
            Konstruktur verwendet wird, behandelt der Indexleser (das <classname>Zend_Search_Lucene
            Objekt</classname>) es wie einen Dateipfad und instanziiert das
            <classname>Zend_Search_Lucene_Storage_Directory_Filesystem</classname> Objekt.
        </para>

        <para>
            Du kannst deinen eigenen Verzeichnisimplementation durch die Erweiterung der
            <classname>Zend_Search_Lucene_Storage_Directory</classname> Klasse definieren.
        </para>

        <para>
            <classname>Zend_Search_Lucene_Storage_Directory</classname> Methoden:
        </para>

        <programlisting language="php"><![CDATA[
abstract class Zend_Search_Lucene_Storage_Directory {
/**
 * Schließt den Speicher
 *
 * @return void
 */
abstract function close();

/**
 * Erstellt im Verzeichnis eine neue, leere Datei mit dem übergebenen Dateinamen $filename.
 *
 * @param string $name
 * @return void
 */
abstract function createFile($filename);

/**
 * Entfernt eine vorhande Datei $filename aus dem Verzeichnis.
 *
 * @param string $filename
 * @return void
 */
abstract function deleteFile($filename);

/**
 * Gibt true zurück, wenn eine Datei mit dem übergebenen Dateinamen $filename existiert
 *
 * @param string $filename
 * @return boolean
 */
abstract function fileExists($filename);

/**
 * Gibt die länge eine Datei $filename im Verzeichnis zurück
 *
 * @param string $filename
 * @return integer
 */
abstract function fileLength($filename);

/**
 * Gibt den UNIX Zeitstempel für die letzte Änderung der Datei $filename zurück.
 *
 * @param string $filename
 * @return integer
 */
abstract function fileModified($filename);

/**
 * Benennt eine vorhandene Datei im Verzeichnis um.
 *
 * @param string $from
 * @param string $to
 * @return void
 */
abstract function renameFile($from, $to);

/**
 * Ändert die Änderungstzeit der Datei $filename auf jetzt um
 *
 * @param string $filename
 * @return void
 */
abstract function touchFile($filename);

/**
 * Gibt ein Zend_Search_Lucene_Storage_File Objekt für den^
 * Dateinamen $filename aus dem Verzeichnis zurück.
 *
 * @param string $filename
 * @return Zend_Search_Lucene_Storage_File
 */
abstract function getFileObject($filename);

}
]]></programlisting>

        <para>
            Die <methodname>getFileObject($filename)</methodname> Methode einer
            <classname>Zend_Search_Lucene_Storage_Directory</classname> Instanz gibt ein
            <classname>Zend_Search_Lucene_Storage_File</classname> Objekt zurück.
        </para>

        <para>
            Die abstrakte Klasse <classname>Zend_Search_Lucene_Storage_File</classname>
            implementiert einfache Funktionen für Dateiabstraktion und das Lesen von Indexdateien.
        </para>

        <para>
            Es muß außerdem <classname>Zend_Search_Lucene_Storage_File</classname> für eine eigene
            Verzeichnisimplementation erweitert werden.
        </para>

        <para>
            Nur zwei Methoden der <classname>Zend_Search_Lucene_Storage_File</classname> Klasse
            müssen in der eigenen Implementation überschrieben werden:
        </para>

        <programlisting language="php"><![CDATA[
class MyFile extends Zend_Search_Lucene_Storage_File {
    /**
     * Setzt den Indikator für die Dateiposition rückt den Dateizeiger
     * voran. Die neue Position, gemessen in Bytes vom Dateianfangm
     * wird erreicht durch das Hinzufügen eines Versatzes zu der
     * angegebenen Position. Dessen Werte sind wie folgt definiert:
     * SEEK_SET - Setze die Position auf den Versatz.
     * SEEK_CUR - Setze die Position auf die aktuelle Position plus Versatz.
     * SEEK_END - Setze die Position aufs Dateisende plus Versatz. (Um den
     * Zeiger auf eine Position vor dem Dateiende zu bewegen, übergebe einen
     * negativen Wert als Versatz.)
     * Bei Erfolg wird 0, andernfalls -1 zurückgegeben
     *
     * @param integer $offset
     * @param integer $whence
     * @return integer
     */
    public function seek($offset, $whence=SEEK_SET) {
        ...
    }

    /**
     * Lese $length Bytes aus der Datei und setze den Dateizeiger vor.
     *
     * @param integer $length
     * @return string
     */
    protected function _fread($length=1) {
        ...
    }
}
]]></programlisting>
    </sect2>
</sect1>