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

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

    <sect2 id="zend.search.lucene.advanced.format_migration">
        <title>A partir da versão 1.6, manipulando as transformações no formato de índice</title>

        <para>
            O componente <classname>Zend_Search_Lucene</classname> trabalha com os formatos de
            índice Java Lucene 1.4-1.9, 2.1 e 2.3.
        </para>

        <para>
            O formato de índice corrente pode ser solicitado através da chamada
            <code>$index->getFormatVersion()</code>. Ela retorna um dos seguintes valores:

            <itemizedlist>
                <listitem>
                    <para>
                        <constant>Zend_Search_Lucene::FORMAT_PRE_2_1</constant> para o formato de
                        índice Java Lucene 1.4-1.9.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Zend_Search_Lucene::FORMAT_2_1</constant> para o formato de índice
                        Java Lucene 2.1 (também usado para Lucene 2.2).
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Zend_Search_Lucene::FORMAT_2_3</constant> para o formato de índice
                        Java Lucene 2.3.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <para>
            As modificações no índice são realizadas <emphasis>apenas</emphasis> se qualquer
            atualização do índice for feita. Isso acontece se um novo documento for adicionado a um
            índice ou uma otimização de índice for iniciada manualmente através da chamada
            <code>$index->optimize()</code>.
        </para>

        <para>
            Nesse caso, <classname>Zend_Search_Lucene</classname> pode converter o índice para a
            versão superior. Isso <emphasis>sempre</emphasis> acontece para os índices no formato
            <constant>Zend_Search_Lucene::FORMAT_PRE_2_1</constant>, que são automaticamente
            convertidos para o formato 2.1.
        </para>

        <para>
            Você pode gerenciar o processo de conversão e atribuir o formato de índice de destino
            com <code>$index->setFormatVersion()</code> que toma como parâmetro a constante
            <constant>Zend_Search_Lucene::FORMAT_2_1</constant> ou
            <constant>Zend_Search_Lucene::FORMAT_2_3</constant>:

            <itemizedlist>
                <listitem>
                    <para>
                        <constant>Zend_Search_Lucene::FORMAT_2_1</constant> na verdade não faz nada
                        desde que os índices pré-2.1 são automaticamente convertidos para
                        formato 2.1.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <constant>Zend_Search_Lucene::FORMAT_2_3</constant> força a conversão para o
                        formato 2.3.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <para>
            Conversões para versões anteriores de formatos não são suportadas.
        </para>

        <note>
            <title>Importante!</title>

            <para>
                Uma vez que o índice é convertido para a versão superior não pode ser convertido de
                volta. Por isso, faça um backup do seu índice quando você planejar a migração para a
                versão superior, mas querendo ter a possibilidade de converter para uma versão
                anterior.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.search.lucene.advanced.static">
        <title>Usando o índice como propriedade estática</title>

        <para>
            The <classname>Zend_Search_Lucene</classname> object uses the destructor method to
            commit changes and clean up resources.
        </para>

        <para>
            It stores added documents in memory and dumps new index segment to disk depending on
            <code>MaxBufferedDocs</code> parameter.
        </para>

        <para>
            If <code>MaxBufferedDocs</code> limit is not reached then there are some "unsaved"
            documents which are saved as a new segment in the object's destructor method. The index
            auto-optimization procedure is invoked if necessary depending on the values of the
            <code>MaxBufferedDocs</code>, <code>MaxMergeDocs</code> and <code>MergeFactor</code>
            parameters.
        </para>

        <para>
            Static object properties (see below) are destroyed <emphasis>after</emphasis> the last
            line of the executed script.
        </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>
            All the same, the destructor for static properties is correctly invoked at this point in
            the program's execution.
        </para>

        <para>
            One potential problem is exception handling. Exceptions thrown by destructors of static
            objects don't have context, because the destructor is executed after the script has
            already completed.
        </para>

        <para>
            You might see a "Fatal error: Exception thrown without a stack frame in Unknown on line
            0" error message instead of exception description in such cases.
        </para>

        <para>
            <classname>Zend_Search_Lucene</classname> provides a workaround to this problem with the
            <methodname>commit()</methodname> method. It saves all unsaved changes and frees memory
            used for storing new segments. You are free to use the commit operation any time- or
            even several times- during script execution. You can still use the
            <classname>Zend_Search_Lucene</classname> object for searching, adding or deleting
            document after the commit operation. But the <methodname>commit()</methodname> call
            guarantees that if there are no document added or deleted after the call to
            <methodname>commit()</methodname>, then the <classname>Zend_Search_Lucene</classname>
            destructor has nothing to do and will not throw exception:
        </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();

...

// Rotina de desligamento do script
...
Searcher::commit();
...
]]></programlisting>
    </sect2>
</sect1>