repo_zf1/documentation/manual/pt-br/module_specs/Zend_Search_Lucene-Extending.xml

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

    <sect2 id="zend.search.lucene.extending.analysis">
        <title>Análise de Texto</title>

        <para>
            A classe <classname>Zend_Search_Lucene_Analysis_Analyzer</classname> é usada pelo
            indexador para "tokenizar" campos de documentos de texto.
        </para>

        <para>
            Os métodos <methodname>Zend_Search_Lucene_Analysis_Analyzer::getDefault()</methodname> e
            <code>Zend_Search_Lucene_Analysis_Analyzer::setDefault()</code> são usados para obter e
            setar, respectivamente, o analisador padrão.
        </para>

        <para>
            Você pode estipular o seu próprio analisador de textos ou selecioná-lo dentre uma lista
            de analisadores prédefinidos:
            <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Text</classname> e
            <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Text_CaseInsensitive</classname>
            (padrão). Ambos interpretam os "tokens" como sequencias de letras.
            <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Text_CaseInsensitive</classname>
            converte todos os "tokens" para caixa baixa.
        </para>

        <para>
            Para selecionar um analisador:
        </para>

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

        <para>
            A classe <classname>Zend_Search_Lucene_Analysis_Analyzer_Common</classname> foi
            projetada para ser um antepassado de todos os analisadores definidos pelo usuário. O
            usuário só precisa definir os métodos <methodname>reset()</methodname> e
            <methodname>nextToken()</methodname>, que receberá a string do membro $_input e
            retornará os "tokens" um por um (um valor <constant>NULL</constant> indica o fim do
            fluxo).
        </para>

        <para>
            O método <methodname>nextToken()</methodname> deve chamar o método
            <methodname>normalize()</methodname> em cada "token". Isso te permite usar filtros de
            "token" junto com o seu analisador.
        </para>

        <para>
            Aqui está um exemplo de um analisador customizado, que aceita palavras contendo dígitos
            como termos:

            <example id="zend.search.lucene.extending.analysis.example-1">
                <title>Analisador de Texto Customizado</title>

                <programlisting language="php"><![CDATA[
/**
 * Here is a custom text analyser, which treats words with digits as
 * one term
 */

class My_Analyzer extends Zend_Search_Lucene_Analysis_Analyzer_Common
{
    private $_position;

    /**
     * Reset token stream
     */
    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>Tokens Filtering</title>

        <para>
            The <classname>Zend_Search_Lucene_Analysis_Analyzer_Common</classname> analyzer also offers a token filtering
            mechanism.
        </para>

        <para>
            The <classname>Zend_Search_Lucene_Analysis_TokenFilter</classname> class provides an abstract interface for such filters.
            Your own filters should extend this class either directly or indirectly.
        </para>

        <para>
            Any custom filter must implement the <methodname>normalize()</methodname> method which may transform input token or signal that
            the current token should be skipped.
        </para>

        <para>
            There are three filters already defined in the analysis subpackage:
            <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>
            The <code>LowerCase</code> filter is already used for
            <classname>Zend_Search_Lucene_Analysis_Analyzer_Common_Text_CaseInsensitive</classname> analyzer
            by default.
        </para>

        <para>
            The <code>ShortWords</code> and <code>StopWords</code> filters may be used with pre-defined or custom
            analyzers like this:

            <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>

        <para>
            The <classname>Zend_Search_Lucene_Analysis_TokenFilter_StopWords</classname> constructor takes an array of stop-words
            as an input. But stop-words may be also loaded from a file:

            <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>

            This file should be a common text file with one word in each line. The '#' character marks a line as a comment.
        </para>

        <para>
            The <classname>Zend_Search_Lucene_Analysis_TokenFilter_ShortWords</classname> constructor has one optional argument.
            This is the word length limit, set by default to 2.
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.extending.scoring">
        <title>Algoritmos de Pontuação</title>

        <para>
            A pontuação de um documento <literal>d</literal> para uma consulta <literal>q</literal>
            é definida como segue:
        </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> - 
            um fator de pontuação baseado na frequência de um termo ou frase em um documento.
        </para>

        <para>
            idf(t) -
            <methodname>Zend_Search_Lucene_Search_Similarity::idf($input, $reader)</methodname> -
            um fator de pontuação para um termo simples com o índice especificado.
        </para>

        <para>
            getBoost(t.field in d) - o fator de reforço para o campo.
        </para>

        <para>
            lengthNorm($term) - O valor de normalização para um campo, dado o número total de termos
            contido nele. Este valor é armazenado junto com o índice. Estes valores, juntamente com
            os campos de reforço, são armazenados em um índice e multiplicados nas pontuações de
            acerto em cada campo, pelo código de busca.
        </para>

        <para>
            Comparações em campos longos são menos precisas, e implementações deste método
            usualmente retornam valores pequenos quando o número de "tokens" é grande, e valores
            grandes quando o número de "tokens" for pequeno.
        </para>

        <para>
            coord(q,d) - <methodname>Zend_Search_Lucene_Search_Similarity::coord($overlap,
                $maxOverlap)</methodname> - um fator de pontuação baseado no quociente de todos os
            termos de busca que um documento contém.
        </para>

        <para>
            A existência de uma grande quantidade de termos de busca indica um grau maior de
            comparação. As implementações deste método usualmente retornam valores significativos
            quando a razão entre estes parâmetros é grande e vice versa.
        </para>

        <para>
            queryNorm(q) - o valor de normalização para uma consulta dado a soma das relevâncias ao
            quadrado de cada termo da consulta. Este valor é então multiplicado pela relevância de
            cada ítem da consulta.
        </para>

        <para>
            Isto não afeta a pontuação, mas a quantidade de tentativas para gerar pontuações em
            comparações entre consultas.
        </para>

        <para>
            O algoritmo de pontuação pode ser customizado pela implementação da sua própria classe
            de similaridade. Para isso crie uma classe descendente de
            <classname>Zend_Search_Lucene_Search_Similarity</classname> como mostrado abaixo, então
            use o método
            <classname>Zend_Search_Lucene_Search_Similarity::setDefault($similarity);</classname>
            para defini-la como padrão.
        </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);
    }

    /**
     * It's not used now. Computes the amount of a sloppy phrase match,
     * based on an edit distance.
     */
    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>Recipientes de Armazenagem</title>

        <para>
            A classe abstrata <classname>Zend_Search_Lucene_Storage_Directory</classname> define a
            funcionalidade de diretório.
        </para>

        <para>
            O construtor do <classname>Zend_Search_Lucene</classname> usa como entrada uma string ou
            um objeto da classe <classname>Zend_Search_Lucene_Storage_Directory</classname>.
        </para>

        <para>
            A classe <classname>Zend_Search_Lucene_Storage_Directory_Filesystem</classname>
            implementa a funcionalidade de diretório para o sistema de arquivos.
        </para>

        <para>
            Se uma string for usada como entrada para o construtor do
            <classname>Zend_Search_Lucene</classname>, então o leitor do índice (um objeto
            <classname>Zend_Search_Lucene</classname>) a tratará como um caminho para o sistema de
            arquivos e instanciará um objeto
            <classname>Zend_Search_Lucene_Storage_Directory_Filesystem</classname>.
        </para>

        <para>
            Você pode definir a sua própria implementação de diretório extendendo a classe
            <classname>Zend_Search_Lucene_Storage_Directory</classname>.
        </para>

        <para>
            Métodos de <classname>Zend_Search_Lucene_Storage_Directory</classname>:
        </para>

        <programlisting language="php"><![CDATA[
abstract class Zend_Search_Lucene_Storage_Directory {
/**
 * Closes the store.
 *
 * @return void
 */
abstract function close();

/**
 * Creates a new, empty file in the directory with the given $filename.
 *
 * @param string $name
 * @return void
 */
abstract function createFile($filename);

/**
 * Removes an existing $filename in the directory.
 *
 * @param string $filename
 * @return void
 */
abstract function deleteFile($filename);

/**
 * Returns true if a file with the given $filename exists.
 *
 * @param string $filename
 * @return boolean
 */
abstract function fileExists($filename);

/**
 * Returns the length of a $filename in the directory.
 *
 * @param string $filename
 * @return integer
 */
abstract function fileLength($filename);

/**
 * Returns the UNIX timestamp $filename was last modified.
 *
 * @param string $filename
 * @return integer
 */
abstract function fileModified($filename);

/**
 * Renames an existing file in the directory.
 *
 * @param string $from
 * @param string $to
 * @return void
 */
abstract function renameFile($from, $to);

/**
 * Sets the modified time of $filename to now.
 *
 * @param string $filename
 * @return void
 */
abstract function touchFile($filename);

/**
 * Returns a Zend_Search_Lucene_Storage_File object for a given
 * $filename in the directory.
 *
 * @param string $filename
 * @return Zend_Search_Lucene_Storage_File
 */
abstract function getFileObject($filename);

}
]]></programlisting>

        <para>
            O método <methodname>getFileObject($filename)</methodname> de uma instância
            <classname>Zend_Search_Lucene_Storage_Directory</classname> retorna um objeto
            <classname>Zend_Search_Lucene_Storage_File</classname>.
        </para>

        <para>
            A classe abstrata <classname>Zend_Search_Lucene_Storage_File</classname> implementa a
            abstração de arquivo e as primitivas de leitura de arquivos de índice.
        </para>

        <para>
            Se fizer isso, você também terá que extender
            <classname>Zend_Search_Lucene_Storage_File</classname> para a sua implementação de
            diretório.
        </para>

        <para>
            Somente dois métodos de <classname>Zend_Search_Lucene_Storage_File</classname> devem ser
            substituídos em sua implementação:
        </para>

        <programlisting language="php"><![CDATA[
class MyFile extends Zend_Search_Lucene_Storage_File {
    /**
     * Sets the file position indicator and advances the file pointer.
     * The new position, measured in bytes from the beginning of the file,
     * is obtained by adding offset to the position specified by whence,
     * whose values are defined as follows:
     * SEEK_SET - Set position equal to offset bytes.
     * SEEK_CUR - Set position to current location plus offset.
     * SEEK_END - Set position to end-of-file plus offset. (To move to
     * a position before the end-of-file, you need to pass a negative value
     * in offset.)
     * Upon success, returns 0; otherwise, returns -1
     *
     * @param integer $offset
     * @param integer $whence
     * @return integer
     */
    public function seek($offset, $whence=SEEK_SET) {
        ...
    }

    /**
     * Read a $length bytes from the file and advance the file pointer.
     *
     * @param integer $length
     * @return string
     */
    protected function _fread($length=1) {
        ...
    }
}
]]></programlisting>

    </sect2>
</sect1>

<!--
vim:se ts=4 sw=4 et:
-->