1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.search.lucene.advanced">
<title>Advanced</title>
<sect2 id="zend.search.lucene.advanced.format_migration">
<title>Starting from 1.6, handling index format transformations</title>
<para>
<classname>Zend_Search_Lucene</classname> component works with Java Lucene 1.4-1.9, 2.1
and 2.3 index formats.
</para>
<para>
Current index format may be requested using <code>$index->getFormatVersion()</code>
call. It returns one of the following values:
<itemizedlist>
<listitem>
<para>
<constant>Zend_Search_Lucene::FORMAT_PRE_2_1</constant> for Java Lucene
1.4-1.9 index format.
</para>
</listitem>
<listitem>
<para>
<constant>Zend_Search_Lucene::FORMAT_2_1</constant> for Java Lucene 2.1
index format (also used for Lucene 2.2).
</para>
</listitem>
<listitem>
<para>
<constant>Zend_Search_Lucene::FORMAT_2_3</constant> for Java Lucene 2.3
index format.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Index modifications are performed <emphasis>only</emphasis> if any index update is done.
That happens if a new document is added to an index or index optimization is started
manually by <code>$index->optimize()</code> call.
</para>
<para>
In a such case <classname>Zend_Search_Lucene</classname> may convert index to the higher
format version. That <emphasis>always</emphasis> happens for the indices in
<constant>Zend_Search_Lucene::FORMAT_PRE_2_1</constant> format, which are automatically
converted to 2.1 format.
</para>
<para>
You may manage conversion process and assign target index format by
<code>$index->setFormatVersion()</code> which takes
<constant>Zend_Search_Lucene::FORMAT_2_1</constant> or
<constant>Zend_Search_Lucene::FORMAT_2_3</constant> constant as a parameter:
<itemizedlist>
<listitem>
<para>
<constant>Zend_Search_Lucene::FORMAT_2_1</constant> actually does nothing
since pre-2.1 indices are automatically converted to 2.1 format.
</para>
</listitem>
<listitem>
<para>
<constant>Zend_Search_Lucene::FORMAT_2_3</constant> forces conversion to the
2.3 format.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Backward conversions are not supported.
</para>
<note>
<title>Important!</title>
<para>
Once index is converted to upper version it can't be converted back. So make a
backup of your index when you plan migration to upper version, but want to have
possibility to go back.
</para>
</note>
</sect2>
<sect2 id="zend.search.lucene.advanced.static">
<title>Using the index as static property</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();
...
// Script shutdown routine
...
Searcher::commit();
...
]]></programlisting>
</sect2>
</sect1>
|
