lucene-java-3.5.0/lucene/src/java/org/apache/lucene/search/Searchable.java

   1 package org.apache.lucene.search;
   2
   3 /**
   4  * Licensed to the Apache Software Foundation (ASF) under one or more
   5  * contributor license agreements.  See the NOTICE file distributed with
   6  * this work for additional information regarding copyright ownership.
   7  * The ASF licenses this file to You under the Apache License, Version 2.0
   8  * (the "License"); you may not use this file except in compliance with
   9  * the License.  You may obtain a copy of the License at
  10  *
  11  *     http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19
  20 import java.io.IOException;
  21 import java.io.Closeable;
  22
  23 import org.apache.lucene.document.Document;
  24 import org.apache.lucene.document.FieldSelector;
  25 import org.apache.lucene.index.CorruptIndexException;
  26 import org.apache.lucene.index.Term;
  27
  28 /**
  29  * The interface for search implementations.
  30  *
  31  * <p>
  32  * Searchable is the abstract network protocol for searching. Implementations
  33  * provide search over a single index, over multiple indices, and over indices
  34  * on remote servers.
  35  *
  36  * <p>
  37  * Queries, filters and sort criteria are designed to be compact so that they
  38  * may be efficiently passed to a remote index, with only the top-scoring hits
  39  * being returned, rather than every matching hit.
  40  *
  41  * <b>NOTE:</b> this interface is kept public for convenience. Since it is not
  42  * expected to be implemented directly, it may be changed unexpectedly between
  43  * releases.
  44  *
  45  * @deprecated In 4.0 this interface is removed/absorbed
  46  * into IndexSearcher
  47  */
  48 @Deprecated
  49 public interface Searchable extends Closeable {
  50
  51   /**
  52    * Lower-level search API.
  53    *
  54    * <p>
  55    * {@link Collector#collect(int)} is called for every document. <br>
  56    * Collector-based access to remote indexes is discouraged.
  57    *
  58    * <p>
  59    * Applications should only use this if they need <i>all</i> of the matching
  60    * documents. The high-level search API ({@link Searcher#search(Query,int)}) is
  61    * usually more efficient, as it skips non-high-scoring hits.
  62    *
  63    * @param weight
  64    *          to match documents
  65    * @param filter
  66    *          if non-null, used to permit documents to be collected.
  67    * @param collector
  68    *          to receive hits
  69    * @throws BooleanQuery.TooManyClauses
  70    */
  71   void search(Weight weight, Filter filter, Collector collector) throws IOException;
  72
  73   /** Frees resources associated with this Searcher.
  74    * Be careful not to call this method while you are still using objects
  75    * that reference this Searchable.
  76    */
  77   void close() throws IOException;
  78
  79   /** Expert: Returns the number of documents containing <code>term</code>.
  80    *
  81    * @see org.apache.lucene.index.IndexReader#docFreq(Term)
  82    */
  83   int docFreq(Term term) throws IOException;
  84
  85   /** Expert: For each term in the terms array, calculates the number of
  86    * documents containing <code>term</code>. Returns an array with these
  87    * document frequencies. Used to minimize number of remote calls.
  88    */
  89   int[] docFreqs(Term[] terms) throws IOException;
  90
  91   /** Expert: Returns one greater than the largest possible document number.
  92    *
  93    * @see org.apache.lucene.index.IndexReader#maxDoc()
  94    */
  95   int maxDoc() throws IOException;
  96
  97   /** Expert: Low-level search implementation.  Finds the top <code>n</code>
  98    * hits for <code>query</code>, applying <code>filter</code> if non-null.
  99    *
 100    * <p>Applications should usually call {@link Searcher#search(Query,int)} or
 101    * {@link Searcher#search(Query,Filter,int)} instead.
 102    * @throws BooleanQuery.TooManyClauses
 103    */
 104   TopDocs search(Weight weight, Filter filter, int n) throws IOException;
 105
 106   /**
 107    * Returns the stored fields of document <code>i</code>.
 108    *
 109    * @see org.apache.lucene.index.IndexReader#document(int)
 110    * @throws CorruptIndexException if the index is corrupt
 111    * @throws IOException if there is a low-level IO error
 112    */
 113   Document doc(int i) throws CorruptIndexException, IOException;
 114
 115   /**
 116    * Get the {@link org.apache.lucene.document.Document} at the <code>n</code><sup>th</sup> position. The {@link org.apache.lucene.document.FieldSelector}
 117    * may be used to determine what {@link org.apache.lucene.document.Field}s to load and how they should be loaded.
 118    *
 119    * <b>NOTE:</b> If the underlying Reader (more specifically, the underlying <code>FieldsReader</code>) is closed before the lazy {@link org.apache.lucene.document.Field} is
 120    * loaded an exception may be thrown.  If you want the value of a lazy {@link org.apache.lucene.document.Field} to be available after closing you must
 121    * explicitly load it or fetch the Document again with a new loader.
 122    *
 123    *
 124    * @param n Get the document at the <code>n</code><sup>th</sup> position
 125    * @param fieldSelector The {@link org.apache.lucene.document.FieldSelector} to use to determine what Fields should be loaded on the Document.  May be null, in which case all Fields will be loaded.
 126    * @return The stored fields of the {@link org.apache.lucene.document.Document} at the nth position
 127    * @throws CorruptIndexException if the index is corrupt
 128    * @throws IOException if there is a low-level IO error
 129    *
 130    * @see org.apache.lucene.index.IndexReader#document(int, FieldSelector)
 131    * @see org.apache.lucene.document.Fieldable
 132    * @see org.apache.lucene.document.FieldSelector
 133    * @see org.apache.lucene.document.SetBasedFieldSelector
 134    * @see org.apache.lucene.document.LoadFirstFieldSelector
 135    */
 136   Document doc(int n, FieldSelector fieldSelector) throws CorruptIndexException, IOException;
 137
 138   /** Expert: called to re-write queries into primitive queries.
 139    * @throws BooleanQuery.TooManyClauses
 140    */
 141   Query rewrite(Query query) throws IOException;
 142
 143   /** Expert: low-level implementation method
 144    * Returns an Explanation that describes how <code>doc</code> scored against
 145    * <code>weight</code>.
 146    *
 147    * <p>This is intended to be used in developing Similarity implementations,
 148    * and, for good performance, should not be displayed with every hit.
 149    * Computing an explanation is as expensive as executing the query over the
 150    * entire index.
 151    * <p>Applications should call {@link Searcher#explain(Query, int)}.
 152    * @throws BooleanQuery.TooManyClauses
 153    */
 154   Explanation explain(Weight weight, int doc) throws IOException;
 155
 156   /** Expert: Low-level search implementation with arbitrary sorting.  Finds
 157    * the top <code>n</code> hits for <code>query</code>, applying
 158    * <code>filter</code> if non-null, and sorting the hits by the criteria in
 159    * <code>sort</code>.
 160    *
 161    * <p>Applications should usually call {@link
 162    * Searcher#search(Query,Filter,int,Sort)} instead.
 163    *
 164    * @throws BooleanQuery.TooManyClauses
 165    */
 166   TopFieldDocs search(Weight weight, Filter filter, int n, Sort sort)
 167   throws IOException;
 168
 169 }