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-2010 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 20096 2010-01-06 02:05:09Z bkarwin $

    20  */

    21 

    22 

    23 /** Zend_Search_Lucene_Index_TermsStream_Interface */

    24 require_once 'Zend/Search/Lucene/Index/TermsStream/Interface.php';

    25 

    26 

    27 /** Classes used within Zend_Search_Lucene_Interface API */

    28 

    29 /** Zend_Search_Lucene_Document */

    30 require_once 'Zend/Search/Lucene/Document.php';

    31 

    32 /** Zend_Search_Lucene_Index_Term */

    33 require_once 'Zend/Search/Lucene/Index/Term.php';

    34 

    35 /** Zend_Search_Lucene_Index_DocsFilter */

    36 require_once 'Zend/Search/Lucene/Index/DocsFilter.php';

    37 

    38 

    39 /**

    40  * @category   Zend

    41  * @package    Zend_Search_Lucene

    42  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

    43  * @license    http://framework.zend.com/license/new-bsd     New BSD License

    44  */

    45 interface Zend_Search_Lucene_Interface extends Zend_Search_Lucene_Index_TermsStream_Interface

    46 {

    47     /**

    48      * Get current generation number

    49      *

    50      * Returns generation number

    51      * 0 means pre-2.1 index format

    52      * -1 means there are no segments files.

    53      *

    54      * @param Zend_Search_Lucene_Storage_Directory $directory

    55      * @return integer

    56      * @throws Zend_Search_Lucene_Exception

    57      */

    58     public static function getActualGeneration(Zend_Search_Lucene_Storage_Directory $directory);

    59 

    60     /**

    61      * Get segments file name

    62      *

    63      * @param integer $generation

    64      * @return string

    65      */

    66     public static function getSegmentFileName($generation);

    67 

    68     /**

    69      * Get index format version

    70      *

    71      * @return integer

    72      */

    73     public function getFormatVersion();

    74 

    75     /**

    76      * Set index format version.

    77      * Index is converted to this format at the nearest upfdate time

    78      *

    79      * @param int $formatVersion

    80      * @throws Zend_Search_Lucene_Exception

    81      */

    82     public function setFormatVersion($formatVersion);

    83 

    84     /**

    85      * Returns the Zend_Search_Lucene_Storage_Directory instance for this index.

    86      *

    87      * @return Zend_Search_Lucene_Storage_Directory

    88      */

    89     public function getDirectory();

    90 

    91     /**

    92      * Returns the total number of documents in this index (including deleted documents).

    93      *

    94      * @return integer

    95      */

    96     public function count();

    97 

    98     /**

    99      * Returns one greater than the largest possible document number.

   100      * This may be used to, e.g., determine how big to allocate a structure which will have

   101      * an element for every document number in an index.

   102      *

   103      * @return integer

   104      */

   105     public function maxDoc();

   106 

   107     /**

   108      * Returns the total number of non-deleted documents in this index.

   109      *

   110      * @return integer

   111      */

   112     public function numDocs();

   113 

   114     /**

   115      * Checks, that document is deleted

   116      *

   117      * @param integer $id

   118      * @return boolean

   119      * @throws Zend_Search_Lucene_Exception    Exception is thrown if $id is out of the range

   120      */

   121     public function isDeleted($id);

   122 

   123     /**

   124      * Set default search field.

   125      *

   126      * Null means, that search is performed through all fields by default

   127      *

   128      * Default value is null

   129      *

   130      * @param string $fieldName

   131      */

   132     public static function setDefaultSearchField($fieldName);

   133 

   134     /**

   135      * Get default search field.

   136      *

   137      * Null means, that search is performed through all fields by default

   138      *

   139      * @return string

   140      */

   141     public static function getDefaultSearchField();

   142 

   143     /**

   144      * Set result set limit.

   145      *

   146      * 0 (default) means no limit

   147      *

   148      * @param integer $limit

   149      */

   150     public static function setResultSetLimit($limit);

   151 

   152     /**

   153      * Set result set limit.

   154      *

   155      * 0 means no limit

   156      *

   157      * @return integer

   158      */

   159     public static function getResultSetLimit();

   160 

   161     /**

   162      * Retrieve index maxBufferedDocs option

   163      *

   164      * maxBufferedDocs is a minimal number of documents required before

   165      * the buffered in-memory documents are written into a new Segment

   166      *

   167      * Default value is 10

   168      *

   169      * @return integer

   170      */

   171     public function getMaxBufferedDocs();

   172 

   173     /**

   174      * Set index maxBufferedDocs option

   175      *

   176      * maxBufferedDocs is a minimal number of documents required before

   177      * the buffered in-memory documents are written into a new Segment

   178      *

   179      * Default value is 10

   180      *

   181      * @param integer $maxBufferedDocs

   182      */

   183     public function setMaxBufferedDocs($maxBufferedDocs);

   184 

   185     /**

   186      * Retrieve index maxMergeDocs option

   187      *

   188      * maxMergeDocs is a largest number of documents ever merged by addDocument().

   189      * Small values (e.g., less than 10,000) are best for interactive indexing,

   190      * as this limits the length of pauses while indexing to a few seconds.

   191      * Larger values are best for batched indexing and speedier searches.

   192      *

   193      * Default value is PHP_INT_MAX

   194      *

   195      * @return integer

   196      */

   197     public function getMaxMergeDocs();

   198 

   199     /**

   200      * Set index maxMergeDocs option

   201      *

   202      * maxMergeDocs is a largest number of documents ever merged by addDocument().

   203      * Small values (e.g., less than 10,000) are best for interactive indexing,

   204      * as this limits the length of pauses while indexing to a few seconds.

   205      * Larger values are best for batched indexing and speedier searches.

   206      *

   207      * Default value is PHP_INT_MAX

   208      *

   209      * @param integer $maxMergeDocs

   210      */

   211     public function setMaxMergeDocs($maxMergeDocs);

   212 

   213     /**

   214      * Retrieve index mergeFactor option

   215      *

   216      * mergeFactor determines how often segment indices are merged by addDocument().

   217      * With smaller values, less RAM is used while indexing,

   218      * and searches on unoptimized indices are faster,

   219      * but indexing speed is slower.

   220      * With larger values, more RAM is used during indexing,

   221      * and while searches on unoptimized indices are slower,

   222      * indexing is faster.

   223      * Thus larger values (> 10) are best for batch index creation,

   224      * and smaller values (< 10) for indices that are interactively maintained.

   225      *

   226      * Default value is 10

   227      *

   228      * @return integer

   229      */

   230     public function getMergeFactor();

   231 

   232     /**

   233      * Set index mergeFactor option

   234      *

   235      * mergeFactor determines how often segment indices are merged by addDocument().

   236      * With smaller values, less RAM is used while indexing,

   237      * and searches on unoptimized indices are faster,

   238      * but indexing speed is slower.

   239      * With larger values, more RAM is used during indexing,

   240      * and while searches on unoptimized indices are slower,

   241      * indexing is faster.

   242      * Thus larger values (> 10) are best for batch index creation,

   243      * and smaller values (< 10) for indices that are interactively maintained.

   244      *

   245      * Default value is 10

   246      *

   247      * @param integer $maxMergeDocs

   248      */

   249     public function setMergeFactor($mergeFactor);

   250 

   251     /**

   252      * Performs a query against the index and returns an array

   253      * of Zend_Search_Lucene_Search_QueryHit objects.

   254      * Input is a string or Zend_Search_Lucene_Search_Query.

   255      *

   256      * @param mixed $query

   257      * @return array Zend_Search_Lucene_Search_QueryHit

   258      * @throws Zend_Search_Lucene_Exception

   259      */

   260     public function find($query);

   261 

   262     /**

   263      * Returns a list of all unique field names that exist in this index.

   264      *

   265      * @param boolean $indexed

   266      * @return array

   267      */

   268     public function getFieldNames($indexed = false);

   269 

   270     /**

   271      * Returns a Zend_Search_Lucene_Document object for the document

   272      * number $id in this index.

   273      *

   274      * @param integer|Zend_Search_Lucene_Search_QueryHit $id

   275      * @return Zend_Search_Lucene_Document

   276      */

   277     public function getDocument($id);

   278 

   279     /**

   280      * Returns true if index contain documents with specified term.

   281      *

   282      * Is used for query optimization.

   283      *

   284      * @param Zend_Search_Lucene_Index_Term $term

   285      * @return boolean

   286      */

   287     public function hasTerm(Zend_Search_Lucene_Index_Term $term);

   288 

   289     /**

   290      * Returns IDs of all the documents containing term.

   291      *

   292      * @param Zend_Search_Lucene_Index_Term $term

   293      * @param Zend_Search_Lucene_Index_DocsFilter|null $docsFilter

   294      * @return array

   295      */

   296     public function termDocs(Zend_Search_Lucene_Index_Term $term, $docsFilter = null);

   297 

   298     /**

   299      * Returns documents filter for all documents containing term.

   300      *

   301      * It performs the same operation as termDocs, but return result as

   302      * Zend_Search_Lucene_Index_DocsFilter object

   303      *

   304      * @param Zend_Search_Lucene_Index_Term $term

   305      * @param Zend_Search_Lucene_Index_DocsFilter|null $docsFilter

   306      * @return Zend_Search_Lucene_Index_DocsFilter

   307      */

   308     public function termDocsFilter(Zend_Search_Lucene_Index_Term $term, $docsFilter = null);

   309 

   310     /**

   311      * Returns an array of all term freqs.

   312      * Return array structure: array( docId => freq, ...)

   313      *

   314      * @param Zend_Search_Lucene_Index_Term $term

   315      * @param Zend_Search_Lucene_Index_DocsFilter|null $docsFilter

   316      * @return integer

   317      */

   318     public function termFreqs(Zend_Search_Lucene_Index_Term $term, $docsFilter = null);

   319 

   320     /**

   321      * Returns an array of all term positions in the documents.

   322      * Return array structure: array( docId => array( pos1, pos2, ...), ...)

   323      *

   324      * @param Zend_Search_Lucene_Index_Term $term

   325      * @param Zend_Search_Lucene_Index_DocsFilter|null $docsFilter

   326      * @return array

   327      */

   328     public function termPositions(Zend_Search_Lucene_Index_Term $term, $docsFilter = null);

   329 

   330     /**

   331      * Returns the number of documents in this index containing the $term.

   332      *

   333      * @param Zend_Search_Lucene_Index_Term $term

   334      * @return integer

   335      */

   336     public function docFreq(Zend_Search_Lucene_Index_Term $term);

   337 

   338     /**

   339      * Retrive similarity used by index reader

   340      *

   341      * @return Zend_Search_Lucene_Search_Similarity

   342      */

   343     public function getSimilarity();

   344 

   345     /**

   346      * Returns a normalization factor for "field, document" pair.

   347      *

   348      * @param integer $id

   349      * @param string $fieldName

   350      * @return float

   351      */

   352     public function norm($id, $fieldName);

   353 

   354     /**

   355      * Returns true if any documents have been deleted from this index.

   356      *

   357      * @return boolean

   358      */

   359     public function hasDeletions();

   360 

   361     /**

   362      * Deletes a document from the index.

   363      * $id is an internal document id

   364      *

   365      * @param integer|Zend_Search_Lucene_Search_QueryHit $id

   366      * @throws Zend_Search_Lucene_Exception

   367      */

   368     public function delete($id);

   369 

   370     /**

   371      * Adds a document to this index.

   372      *

   373      * @param Zend_Search_Lucene_Document $document

   374      */

   375     public function addDocument(Zend_Search_Lucene_Document $document);

   376 

   377     /**

   378      * Commit changes resulting from delete() or undeleteAll() operations.

   379      */

   380     public function commit();

   381 

   382     /**

   383      * Optimize index.

   384      *

   385      * Merges all segments into one

   386      */

   387     public function optimize();

   388 

   389     /**

   390      * Returns an array of all terms in this index.

   391      *

   392      * @return array

   393      */

   394     public function terms();

   395 

   396     /**

   397      * Undeletes all documents currently marked as deleted in this index.

   398      */

   399     public function undeleteAll();

   400 

   401 

   402     /**

   403      * Add reference to the index object

   404      *

   405      * @internal

   406      */

   407     public function addReference();

   408 

   409     /**

   410      * Remove reference from the index object

   411      *

   412      * When reference count becomes zero, index is closed and resources are cleaned up

   413      *

   414      * @internal

   415      */

   416     public function removeReference();

   417 }