search/Zend/Search/Lucene/Interface.php

   1 <?php
   2 /**
   3  * Zend Framework
   4  *
   5  * LICENSE
   6  *
   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.
  14  *
  15  * @category   Zend
  16  * @package    Zend_Search_Lucene
  17  * @copyright  Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
  18  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  19  */
  20
  21
  22 /**
  23  * @category   Zend
  24  * @package    Zend_Search_Lucene
  25  * @copyright  Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
  26  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  27  */
  28 interface Zend_Search_Lucene_Interface
  29 {
  30     /**
  31      * Returns the Zend_Search_Lucene_Storage_Directory instance for this index.
  32      *
  33      * @return Zend_Search_Lucene_Storage_Directory
  34      */
  35     public function getDirectory();
  36
  37     /**
  38      * Returns the total number of documents in this index (including deleted documents).
  39      *
  40      * @return integer
  41      */
  42     public function count();
  43
  44     /**
  45      * Returns one greater than the largest possible document number.
  46      * This may be used to, e.g., determine how big to allocate a structure which will have
  47      * an element for every document number in an index.
  48      *
  49      * @return integer
  50      */
  51     public function maxDoc();
  52
  53     /**
  54      * Returns the total number of non-deleted documents in this index.
  55      *
  56      * @return integer
  57      */
  58     public function numDocs();
  59
  60     /**
  61      * Checks, that document is deleted
  62      *
  63      * @param integer $id
  64      * @return boolean
  65      * @throws Zend_Search_Lucene_Exception    Exception is thrown if $id is out of the range
  66      */
  67     public function isDeleted($id);
  68
  69     /**
  70      * Set default search field.
  71      *
  72      * Null means, that search is performed through all fields by default
  73      *
  74      * Default value is null
  75      *
  76      * @param string $fieldName
  77      */
  78     public static function setDefaultSearchField($fieldName);
  79
  80     /**
  81      * Get default search field.
  82      *
  83      * Null means, that search is performed through all fields by default
  84      *
  85      * @return string
  86      */
  87     public static function getDefaultSearchField();
  88
  89     /**
  90      * Retrieve index maxBufferedDocs option
  91      *
  92      * maxBufferedDocs is a minimal number of documents required before
  93      * the buffered in-memory documents are written into a new Segment
  94      *
  95      * Default value is 10
  96      *
  97      * @return integer
  98      */
  99     public function getMaxBufferedDocs();
 100
 101     /**
 102      * Set index maxBufferedDocs option
 103      *
 104      * maxBufferedDocs is a minimal number of documents required before
 105      * the buffered in-memory documents are written into a new Segment
 106      *
 107      * Default value is 10
 108      *
 109      * @param integer $maxBufferedDocs
 110      */
 111     public function setMaxBufferedDocs($maxBufferedDocs);
 112
 113     /**
 114      * Retrieve index maxMergeDocs option
 115      *
 116      * maxMergeDocs is a largest number of documents ever merged by addDocument().
 117      * Small values (e.g., less than 10,000) are best for interactive indexing,
 118      * as this limits the length of pauses while indexing to a few seconds.
 119      * Larger values are best for batched indexing and speedier searches.
 120      *
 121      * Default value is PHP_INT_MAX
 122      *
 123      * @return integer
 124      */
 125     public function getMaxMergeDocs();
 126
 127     /**
 128      * Set index maxMergeDocs option
 129      *
 130      * maxMergeDocs is a largest number of documents ever merged by addDocument().
 131      * Small values (e.g., less than 10,000) are best for interactive indexing,
 132      * as this limits the length of pauses while indexing to a few seconds.
 133      * Larger values are best for batched indexing and speedier searches.
 134      *
 135      * Default value is PHP_INT_MAX
 136      *
 137      * @param integer $maxMergeDocs
 138      */
 139     public function setMaxMergeDocs($maxMergeDocs);
 140
 141     /**
 142      * Retrieve index mergeFactor option
 143      *
 144      * mergeFactor determines how often segment indices are merged by addDocument().
 145      * With smaller values, less RAM is used while indexing,
 146      * and searches on unoptimized indices are faster,
 147      * but indexing speed is slower.
 148      * With larger values, more RAM is used during indexing,
 149      * and while searches on unoptimized indices are slower,
 150      * indexing is faster.
 151      * Thus larger values (> 10) are best for batch index creation,
 152      * and smaller values (< 10) for indices that are interactively maintained.
 153      *
 154      * Default value is 10
 155      *
 156      * @return integer
 157      */
 158     public function getMergeFactor();
 159
 160     /**
 161      * Set index mergeFactor option
 162      *
 163      * mergeFactor determines how often segment indices are merged by addDocument().
 164      * With smaller values, less RAM is used while indexing,
 165      * and searches on unoptimized indices are faster,
 166      * but indexing speed is slower.
 167      * With larger values, more RAM is used during indexing,
 168      * and while searches on unoptimized indices are slower,
 169      * indexing is faster.
 170      * Thus larger values (> 10) are best for batch index creation,
 171      * and smaller values (< 10) for indices that are interactively maintained.
 172      *
 173      * Default value is 10
 174      *
 175      * @param integer $maxMergeDocs
 176      */
 177     public function setMergeFactor($mergeFactor);
 178
 179     /**
 180      * Performs a query against the index and returns an array
 181      * of Zend_Search_Lucene_Search_QueryHit objects.
 182      * Input is a string or Zend_Search_Lucene_Search_Query.
 183      *
 184      * @param mixed $query
 185      * @return array Zend_Search_Lucene_Search_QueryHit
 186      * @throws Zend_Search_Lucene_Exception
 187      */
 188     public function find($query);
 189
 190     /**
 191      * Returns a list of all unique field names that exist in this index.
 192      *
 193      * @param boolean $indexed
 194      * @return array
 195      */
 196     public function getFieldNames($indexed = false);
 197
 198     /**
 199      * Returns a Zend_Search_Lucene_Document object for the document
 200      * number $id in this index.
 201      *
 202      * @param integer|Zend_Search_Lucene_Search_QueryHit $id
 203      * @return Zend_Search_Lucene_Document
 204      */
 205     public function getDocument($id);
 206
 207     /**
 208      * Returns true if index contain documents with specified term.
 209      *
 210      * Is used for query optimization.
 211      *
 212      * @param Zend_Search_Lucene_Index_Term $term
 213      * @return boolean
 214      */
 215     public function hasTerm(Zend_Search_Lucene_Index_Term $term);
 216
 217     /**
 218      * Returns IDs of all the documents containing term.
 219      *
 220      * @param Zend_Search_Lucene_Index_Term $term
 221      * @return array
 222      */
 223     public function termDocs(Zend_Search_Lucene_Index_Term $term);
 224
 225     /**
 226      * Returns an array of all term freqs.
 227      * Return array structure: array( docId => freq, ...)
 228      *
 229      * @param Zend_Search_Lucene_Index_Term $term
 230      * @return integer
 231      */
 232     public function termFreqs(Zend_Search_Lucene_Index_Term $term);
 233
 234     /**
 235      * Returns an array of all term positions in the documents.
 236      * Return array structure: array( docId => array( pos1, pos2, ...), ...)
 237      *
 238      * @param Zend_Search_Lucene_Index_Term $term
 239      * @return array
 240      */
 241     public function termPositions(Zend_Search_Lucene_Index_Term $term);
 242
 243     /**
 244      * Returns the number of documents in this index containing the $term.
 245      *
 246      * @param Zend_Search_Lucene_Index_Term $term
 247      * @return integer
 248      */
 249     public function docFreq(Zend_Search_Lucene_Index_Term $term);
 250
 251     /**
 252      * Retrive similarity used by index reader
 253      *
 254      * @return Zend_Search_Lucene_Search_Similarity
 255      */
 256     public function getSimilarity();
 257
 258     /**
 259      * Returns a normalization factor for "field, document" pair.
 260      *
 261      * @param integer $id
 262      * @param string $fieldName
 263      * @return float
 264      */
 265     public function norm($id, $fieldName);
 266
 267     /**
 268      * Returns true if any documents have been deleted from this index.
 269      *
 270      * @return boolean
 271      */
 272     public function hasDeletions();
 273
 274     /**
 275      * Deletes a document from the index.
 276      * $id is an internal document id
 277      *
 278      * @param integer|Zend_Search_Lucene_Search_QueryHit $id
 279      * @throws Zend_Search_Lucene_Exception
 280      */
 281     public function delete($id);
 282
 283     /**
 284      * Adds a document to this index.
 285      *
 286      * @param Zend_Search_Lucene_Document $document
 287      */
 288     public function addDocument(Zend_Search_Lucene_Document $document);
 289
 290     /**
 291      * Commit changes resulting from delete() or undeleteAll() operations.
 292      */
 293     public function commit();
 294
 295     /**
 296      * Optimize index.
 297      *
 298      * Merges all segments into one
 299      */
 300     public function optimize();
 301
 302     /**
 303      * Returns an array of all terms in this index.
 304      *
 305      * @return array
 306      */
 307     public function terms();
 308
 309     /**
 310      * Undeletes all documents currently marked as deleted in this index.
 311      */
 312     public function undeleteAll();
 313
 314
 315     /**
 316      * Add reference to the index object
 317      *
 318      * @internal
 319      */
 320     public function addReference();
 321
 322     /**
 323      * Remove reference from the index object
 324      *
 325      * When reference count becomes zero, index is closed and resources are cleaned up
 326      *
 327      * @internal
 328      */
 329     public function removeReference();
 330 }