7 * This source file is subject to the new BSD license that is bundled
8 * with this package in the file LICENSE.txt.
9 * It is also available through the world-wide-web at this URL:
10 * http://framework.zend.com/license/new-bsd
11 * If you did not receive a copy of the license and are unable to
12 * obtain it through the world-wide-web, please send an email
13 * to license@zend.com so we can send you a copy immediately.
16 * @package Zend_Search_Lucene
17 * @copyright Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
18 * @license http://framework.zend.com/license/new-bsd New BSD License
19 * @version $Id: Interface.php 16971 2009-07-22 18:05:45Z mikaelkael $
22 /** Zend_Search_Lucene_Index_TermsStream_Interface */
23 require_once 'Zend/Search/Lucene/Index/TermsStream/Interface.php';
28 * @package Zend_Search_Lucene
29 * @copyright Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
30 * @license http://framework.zend.com/license/new-bsd New BSD License
32 interface Zend_Search_Lucene_Interface extends Zend_Search_Lucene_Index_TermsStream_Interface
35 * Get current generation number
37 * Returns generation number
38 * 0 means pre-2.1 index format
39 * -1 means there are no segments files.
41 * @param Zend_Search_Lucene_Storage_Directory $directory
43 * @throws Zend_Search_Lucene_Exception
45 public static function getActualGeneration(Zend_Search_Lucene_Storage_Directory $directory);
48 * Get segments file name
50 * @param integer $generation
53 public static function getSegmentFileName($generation);
56 * Get index format version
60 public function getFormatVersion();
63 * Set index format version.
64 * Index is converted to this format at the nearest upfdate time
66 * @param int $formatVersion
67 * @throws Zend_Search_Lucene_Exception
69 public function setFormatVersion($formatVersion);
72 * Returns the Zend_Search_Lucene_Storage_Directory instance for this index.
74 * @return Zend_Search_Lucene_Storage_Directory
76 public function getDirectory();
79 * Returns the total number of documents in this index (including deleted documents).
83 public function count();
86 * Returns one greater than the largest possible document number.
87 * This may be used to, e.g., determine how big to allocate a structure which will have
88 * an element for every document number in an index.
92 public function maxDoc();
95 * Returns the total number of non-deleted documents in this index.
99 public function numDocs();
102 * Checks, that document is deleted
106 * @throws Zend_Search_Lucene_Exception Exception is thrown if $id is out of the range
108 public function isDeleted($id);
111 * Set default search field.
113 * Null means, that search is performed through all fields by default
115 * Default value is null
117 * @param string $fieldName
119 public static function setDefaultSearchField($fieldName);
122 * Get default search field.
124 * Null means, that search is performed through all fields by default
128 public static function getDefaultSearchField();
131 * Set result set limit.
133 * 0 (default) means no limit
135 * @param integer $limit
137 public static function setResultSetLimit($limit);
140 * Set result set limit.
146 public static function getResultSetLimit();
149 * Retrieve index maxBufferedDocs option
151 * maxBufferedDocs is a minimal number of documents required before
152 * the buffered in-memory documents are written into a new Segment
154 * Default value is 10
158 public function getMaxBufferedDocs();
161 * Set index maxBufferedDocs option
163 * maxBufferedDocs is a minimal number of documents required before
164 * the buffered in-memory documents are written into a new Segment
166 * Default value is 10
168 * @param integer $maxBufferedDocs
170 public function setMaxBufferedDocs($maxBufferedDocs);
173 * Retrieve index maxMergeDocs option
175 * maxMergeDocs is a largest number of documents ever merged by addDocument().
176 * Small values (e.g., less than 10,000) are best for interactive indexing,
177 * as this limits the length of pauses while indexing to a few seconds.
178 * Larger values are best for batched indexing and speedier searches.
180 * Default value is PHP_INT_MAX
184 public function getMaxMergeDocs();
187 * Set index maxMergeDocs option
189 * maxMergeDocs is a largest number of documents ever merged by addDocument().
190 * Small values (e.g., less than 10,000) are best for interactive indexing,
191 * as this limits the length of pauses while indexing to a few seconds.
192 * Larger values are best for batched indexing and speedier searches.
194 * Default value is PHP_INT_MAX
196 * @param integer $maxMergeDocs
198 public function setMaxMergeDocs($maxMergeDocs);
201 * Retrieve index mergeFactor option
203 * mergeFactor determines how often segment indices are merged by addDocument().
204 * With smaller values, less RAM is used while indexing,
205 * and searches on unoptimized indices are faster,
206 * but indexing speed is slower.
207 * With larger values, more RAM is used during indexing,
208 * and while searches on unoptimized indices are slower,
209 * indexing is faster.
210 * Thus larger values (> 10) are best for batch index creation,
211 * and smaller values (< 10) for indices that are interactively maintained.
213 * Default value is 10
217 public function getMergeFactor();
220 * Set index mergeFactor option
222 * mergeFactor determines how often segment indices are merged by addDocument().
223 * With smaller values, less RAM is used while indexing,
224 * and searches on unoptimized indices are faster,
225 * but indexing speed is slower.
226 * With larger values, more RAM is used during indexing,
227 * and while searches on unoptimized indices are slower,
228 * indexing is faster.
229 * Thus larger values (> 10) are best for batch index creation,
230 * and smaller values (< 10) for indices that are interactively maintained.
232 * Default value is 10
234 * @param integer $maxMergeDocs
236 public function setMergeFactor($mergeFactor);
239 * Performs a query against the index and returns an array
240 * of Zend_Search_Lucene_Search_QueryHit objects.
241 * Input is a string or Zend_Search_Lucene_Search_Query.
243 * @param mixed $query
244 * @return array Zend_Search_Lucene_Search_QueryHit
245 * @throws Zend_Search_Lucene_Exception
247 public function find($query);
250 * Returns a list of all unique field names that exist in this index.
252 * @param boolean $indexed
255 public function getFieldNames($indexed = false);
258 * Returns a Zend_Search_Lucene_Document object for the document
259 * number $id in this index.
261 * @param integer|Zend_Search_Lucene_Search_QueryHit $id
262 * @return Zend_Search_Lucene_Document
264 public function getDocument($id);
267 * Returns true if index contain documents with specified term.
269 * Is used for query optimization.
271 * @param Zend_Search_Lucene_Index_Term $term
274 public function hasTerm(Zend_Search_Lucene_Index_Term $term);
277 * Returns IDs of all the documents containing term.
279 * @param Zend_Search_Lucene_Index_Term $term
280 * @param Zend_Search_Lucene_Index_DocsFilter|null $docsFilter
283 public function termDocs(Zend_Search_Lucene_Index_Term $term, $docsFilter = null);
286 * Returns documents filter for all documents containing term.
288 * It performs the same operation as termDocs, but return result as
289 * Zend_Search_Lucene_Index_DocsFilter object
291 * @param Zend_Search_Lucene_Index_Term $term
292 * @param Zend_Search_Lucene_Index_DocsFilter|null $docsFilter
293 * @return Zend_Search_Lucene_Index_DocsFilter
295 public function termDocsFilter(Zend_Search_Lucene_Index_Term $term, $docsFilter = null);
298 * Returns an array of all term freqs.
299 * Return array structure: array( docId => freq, ...)
301 * @param Zend_Search_Lucene_Index_Term $term
302 * @param Zend_Search_Lucene_Index_DocsFilter|null $docsFilter
305 public function termFreqs(Zend_Search_Lucene_Index_Term $term, $docsFilter = null);
308 * Returns an array of all term positions in the documents.
309 * Return array structure: array( docId => array( pos1, pos2, ...), ...)
311 * @param Zend_Search_Lucene_Index_Term $term
312 * @param Zend_Search_Lucene_Index_DocsFilter|null $docsFilter
315 public function termPositions(Zend_Search_Lucene_Index_Term $term, $docsFilter = null);
318 * Returns the number of documents in this index containing the $term.
320 * @param Zend_Search_Lucene_Index_Term $term
323 public function docFreq(Zend_Search_Lucene_Index_Term $term);
326 * Retrive similarity used by index reader
328 * @return Zend_Search_Lucene_Search_Similarity
330 public function getSimilarity();
333 * Returns a normalization factor for "field, document" pair.
336 * @param string $fieldName
339 public function norm($id, $fieldName);
342 * Returns true if any documents have been deleted from this index.
346 public function hasDeletions();
349 * Deletes a document from the index.
350 * $id is an internal document id
352 * @param integer|Zend_Search_Lucene_Search_QueryHit $id
353 * @throws Zend_Search_Lucene_Exception
355 public function delete($id);
358 * Adds a document to this index.
360 * @param Zend_Search_Lucene_Document $document
362 public function addDocument(Zend_Search_Lucene_Document $document);
365 * Commit changes resulting from delete() or undeleteAll() operations.
367 public function commit();
372 * Merges all segments into one
374 public function optimize();
377 * Returns an array of all terms in this index.
381 public function terms();
384 * Undeletes all documents currently marked as deleted in this index.
386 public function undeleteAll();
390 * Add reference to the index object
394 public function addReference();
397 * Remove reference from the index object
399 * When reference count becomes zero, index is closed and resources are cleaned up
403 public function removeReference();