documentation/manual/en/module_specs/Zend_Search_Lucene-Advanced.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.search.lucene.advanced">
   4     <title>Advanced</title>
   5
   6     <sect2 id="zend.search.lucene.advanced.format_migration">
   7         <title>Starting from 1.6, handling index format transformations</title>
   8
   9         <para>
  10             <classname>Zend_Search_Lucene</classname> component works with Java Lucene 1.4-1.9, 2.1
  11             and 2.3 index formats.
  12         </para>
  13
  14         <para>
  15             Current index format may be requested using <code>$index->getFormatVersion()</code>
  16             call. It returns one of the following values:
  17
  18             <itemizedlist>
  19                 <listitem>
  20                     <para>
  21                         <constant>Zend_Search_Lucene::FORMAT_PRE_2_1</constant> for Java Lucene
  22                         1.4-1.9 index format.
  23                     </para>
  24                 </listitem>
  25
  26                 <listitem>
  27                     <para>
  28                         <constant>Zend_Search_Lucene::FORMAT_2_1</constant> for Java Lucene 2.1
  29                         index format (also used for Lucene 2.2).
  30                     </para>
  31                 </listitem>
  32
  33                 <listitem>
  34                     <para>
  35                         <constant>Zend_Search_Lucene::FORMAT_2_3</constant> for Java Lucene 2.3
  36                         index format.
  37                     </para>
  38                 </listitem>
  39             </itemizedlist>
  40         </para>
  41
  42         <para>
  43             Index modifications are performed <emphasis>only</emphasis> if any index update is done.
  44             That happens if a new document is added to an index or index optimization is started
  45             manually by <code>$index->optimize()</code> call.
  46         </para>
  47
  48         <para>
  49             In a such case <classname>Zend_Search_Lucene</classname> may convert index to the higher
  50             format version. That <emphasis>always</emphasis> happens for the indices in
  51             <constant>Zend_Search_Lucene::FORMAT_PRE_2_1</constant> format, which are automatically
  52             converted to 2.1 format.
  53         </para>
  54
  55         <para>
  56             You may manage conversion process and assign target index format by
  57             <code>$index->setFormatVersion()</code> which takes
  58             <constant>Zend_Search_Lucene::FORMAT_2_1</constant> or
  59             <constant>Zend_Search_Lucene::FORMAT_2_3</constant> constant as a parameter:
  60
  61             <itemizedlist>
  62                 <listitem>
  63                     <para>
  64                         <constant>Zend_Search_Lucene::FORMAT_2_1</constant> actually does nothing
  65                         since pre-2.1 indices are automatically converted to 2.1 format.
  66                     </para>
  67                 </listitem>
  68                 <listitem>
  69                     <para>
  70                         <constant>Zend_Search_Lucene::FORMAT_2_3</constant> forces conversion to the
  71                         2.3 format.
  72                     </para>
  73                 </listitem>
  74             </itemizedlist>
  75         </para>
  76
  77         <para>
  78             Backward conversions are not supported.
  79         </para>
  80
  81         <note>
  82             <title>Important!</title>
  83
  84             <para>
  85                 Once index is converted to upper version it can't be converted back. So make a
  86                 backup of your index when you plan migration to upper version, but want to have
  87                 possibility to go back.
  88             </para>
  89         </note>
  90     </sect2>
  91
  92     <sect2 id="zend.search.lucene.advanced.static">
  93         <title>Using the index as static property</title>
  94
  95         <para>
  96             The <classname>Zend_Search_Lucene</classname> object uses the destructor method to
  97             commit changes and clean up resources.
  98         </para>
  99
 100         <para>
 101             It stores added documents in memory and dumps new index segment to disk depending on
 102             <code>MaxBufferedDocs</code> parameter.
 103         </para>
 104
 105         <para>
 106             If <code>MaxBufferedDocs</code> limit is not reached then there are some "unsaved"
 107             documents which are saved as a new segment in the object's destructor method. The index
 108             auto-optimization procedure is invoked if necessary depending on the values of the
 109             <code>MaxBufferedDocs</code>, <code>MaxMergeDocs</code> and <code>MergeFactor</code>
 110             parameters.
 111         </para>
 112
 113         <para>
 114             Static object properties (see below) are destroyed <emphasis>after</emphasis> the last
 115             line of the executed script.
 116
 117             <programlisting language="php"><![CDATA[
 118 class Searcher {
 119     private static $_index;
 120
 121     public static function initIndex() {
 122         self::$_index = Zend_Search_Lucene::open('path/to/index');
 123     }
 124 }
 125
 126 Searcher::initIndex();
 127 ]]></programlisting>
 128         </para>
 129
 130         <para>
 131             All the same, the destructor for static properties is correctly invoked at this point in
 132             the program's execution.
 133         </para>
 134
 135         <para>
 136             One potential problem is exception handling. Exceptions thrown by destructors of static
 137             objects don't have context, because the destructor is executed after the script has
 138             already completed.
 139         </para>
 140
 141         <para>
 142             You might see a "Fatal error: Exception thrown without a stack frame in Unknown on line
 143             0" error message instead of exception description in such cases.
 144         </para>
 145
 146         <para>
 147             <classname>Zend_Search_Lucene</classname> provides a workaround to this problem with the
 148             <methodname>commit()</methodname> method. It saves all unsaved changes and frees memory
 149             used for storing new segments. You are free to use the commit operation any time- or
 150             even several times- during script execution. You can still use the
 151             <classname>Zend_Search_Lucene</classname> object for searching, adding or deleting
 152             document after the commit operation. But the <methodname>commit()</methodname> call
 153             guarantees that if there are no document added or deleted after the call to
 154             <methodname>commit()</methodname>, then the <classname>Zend_Search_Lucene</classname>
 155             destructor has nothing to do and will not throw exception:
 156
 157             <programlisting language="php"><![CDATA[
 158 class Searcher {
 159     private static $_index;
 160
 161     public static function initIndex() {
 162         self::$_index = Zend_Search_Lucene::open('path/to/index');
 163     }
 164
 165     ...
 166
 167     public static function commit() {
 168         self::$_index->commit();
 169     }
 170 }
 171
 172 Searcher::initIndex();
 173
 174 ...
 175
 176 // Script shutdown routine
 177 ...
 178 Searcher::commit();
 179 ...
 180 ]]></programlisting>
 181         </para>
 182     </sect2>
 183 </sect1>