lucene-java-3.5.0/lucene/src/java/org/apache/lucene/search/Searcher.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
  22 import org.apache.lucene.document.Document;
  23 import org.apache.lucene.index.CorruptIndexException;
  24 import org.apache.lucene.index.Term;
  25 import org.apache.lucene.document.FieldSelector;
  26
  27 /**
  28  * An abstract base class for search implementations. Implements the main search
  29  * methods.
  30  *
  31  * <p>
  32  * Note that you can only access hits from a Searcher as long as it is not yet
  33  * closed, otherwise an IOException will be thrown.
  34  *
  35  * @deprecated In 4.0 this abstract class is removed/absorbed
  36  * into IndexSearcher
  37  */
  38 @Deprecated
  39 public abstract class Searcher implements Searchable {
  40   /** Search implementation with arbitrary sorting.  Finds
  41    * the top <code>n</code> hits for <code>query</code>, applying
  42    * <code>filter</code> if non-null, and sorting the hits by the criteria in
  43    * <code>sort</code>.
  44    *
  45    * <p>NOTE: this does not compute scores by default; use
  46    * {@link IndexSearcher#setDefaultFieldSortScoring} to
  47    * enable scoring.
  48    *
  49    * @throws BooleanQuery.TooManyClauses
  50    */
  51   public TopFieldDocs search(Query query, Filter filter, int n,
  52                              Sort sort) throws IOException {
  53     return search(createNormalizedWeight(query), filter, n, sort);
  54   }
  55
  56   /**
  57    * Search implementation with arbitrary sorting and no filter.
  58    * @param query The query to search for
  59    * @param n Return only the top n results
  60    * @param sort The {@link org.apache.lucene.search.Sort} object
  61    * @return The top docs, sorted according to the supplied {@link org.apache.lucene.search.Sort} instance
  62    * @throws IOException
  63    */
  64   public TopFieldDocs search(Query query, int n,
  65                              Sort sort) throws IOException {
  66     return search(createNormalizedWeight(query), null, n, sort);
  67   }
  68
  69   /** Lower-level search API.
  70   *
  71   * <p>{@link Collector#collect(int)} is called for every matching document.
  72   *
  73   * <p>Applications should only use this if they need <i>all</i> of the
  74   * matching documents.  The high-level search API ({@link
  75   * Searcher#search(Query, int)}) is usually more efficient, as it skips
  76   * non-high-scoring hits.
  77   * <p>Note: The <code>score</code> passed to this method is a raw score.
  78   * In other words, the score will not necessarily be a float whose value is
  79   * between 0 and 1.
  80   * @throws BooleanQuery.TooManyClauses
  81   */
  82  public void search(Query query, Collector results)
  83    throws IOException {
  84    search(createNormalizedWeight(query), null, results);
  85  }
  86
  87   /** Lower-level search API.
  88    *
  89    * <p>{@link Collector#collect(int)} is called for every matching
  90    * document.
  91    * <br>Collector-based access to remote indexes is discouraged.
  92    *
  93    * <p>Applications should only use this if they need <i>all</i> of the
  94    * matching documents.  The high-level search API ({@link
  95    * Searcher#search(Query, Filter, int)}) is usually more efficient, as it skips
  96    * non-high-scoring hits.
  97    *
  98    * @param query to match documents
  99    * @param filter if non-null, used to permit documents to be collected.
 100    * @param results to receive hits
 101    * @throws BooleanQuery.TooManyClauses
 102    */
 103   public void search(Query query, Filter filter, Collector results)
 104   throws IOException {
 105     search(createNormalizedWeight(query), filter, results);
 106   }
 107
 108   /** Finds the top <code>n</code>
 109    * hits for <code>query</code>, applying <code>filter</code> if non-null.
 110    *
 111    * @throws BooleanQuery.TooManyClauses
 112    */
 113   public TopDocs search(Query query, Filter filter, int n)
 114     throws IOException {
 115     return search(createNormalizedWeight(query), filter, n);
 116   }
 117
 118   /** Finds the top <code>n</code>
 119    * hits for <code>query</code>.
 120    *
 121    * @throws BooleanQuery.TooManyClauses
 122    */
 123   public TopDocs search(Query query, int n)
 124     throws IOException {
 125     return search(query, null, n);
 126   }
 127
 128   /** Returns an Explanation that describes how <code>doc</code> scored against
 129    * <code>query</code>.
 130    *
 131    * <p>This is intended to be used in developing Similarity implementations,
 132    * and, for good performance, should not be displayed with every hit.
 133    * Computing an explanation is as expensive as executing the query over the
 134    * entire index.
 135    */
 136   public Explanation explain(Query query, int doc) throws IOException {
 137     return explain(createNormalizedWeight(query), doc);
 138   }
 139
 140   /** The Similarity implementation used by this searcher. */
 141   private Similarity similarity = Similarity.getDefault();
 142
 143   /** Expert: Set the Similarity implementation used by this Searcher.
 144    *
 145    * @see Similarity#setDefault(Similarity)
 146    */
 147   public void setSimilarity(Similarity similarity) {
 148     this.similarity = similarity;
 149   }
 150
 151   /** Expert: Return the Similarity implementation used by this Searcher.
 152    *
 153    * <p>This defaults to the current value of {@link Similarity#getDefault()}.
 154    */
 155   public Similarity getSimilarity() {
 156     return this.similarity;
 157   }
 158
 159   /**
 160    * Creates a normalized weight for a top-level {@link Query}.
 161    * The query is rewritten by this method and {@link Query#createWeight} called,
 162    * afterwards the {@link Weight} is normalized. The returned {@code Weight}
 163    * can then directly be used to get a {@link Scorer}.
 164    * @lucene.internal
 165    */
 166   public Weight createNormalizedWeight(Query query) throws IOException {
 167     query = rewrite(query);
 168     Weight weight = query.createWeight(this);
 169     float sum = weight.sumOfSquaredWeights();
 170     // this is a hack for backwards compatibility:
 171     float norm = query.getSimilarity(this).queryNorm(sum);
 172     if (Float.isInfinite(norm) || Float.isNaN(norm))
 173       norm = 1.0f;
 174     weight.normalize(norm);
 175     return weight;
 176   }
 177
 178   /**
 179    * Expert: Creates a normalized weight for a top-level {@link Query}.
 180    * The query is rewritten by this method and {@link Query#createWeight} called,
 181    * afterwards the {@link Weight} is normalized. The returned {@code Weight}
 182    * can then directly be used to get a {@link Scorer}.
 183    * @deprecated never ever use this method in {@link Weight} implementations.
 184    * Subclasses of Searcher should use {@link #createNormalizedWeight}, instead.
 185    */
 186   @Deprecated
 187   protected final Weight createWeight(Query query) throws IOException {
 188     return createNormalizedWeight(query);
 189   }
 190
 191   // inherit javadoc
 192   public int[] docFreqs(Term[] terms) throws IOException {
 193     int[] result = new int[terms.length];
 194     for (int i = 0; i < terms.length; i++) {
 195       result[i] = docFreq(terms[i]);
 196     }
 197     return result;
 198   }
 199
 200   abstract public void search(Weight weight, Filter filter, Collector results) throws IOException;
 201   abstract public void close() throws IOException;
 202   abstract public int docFreq(Term term) throws IOException;
 203   abstract public int maxDoc() throws IOException;
 204   abstract public TopDocs search(Weight weight, Filter filter, int n) throws IOException;
 205   abstract public Document doc(int i) throws CorruptIndexException, IOException;
 206   abstract public Document doc(int docid, FieldSelector fieldSelector) throws CorruptIndexException, IOException;
 207   abstract public Query rewrite(Query query) throws IOException;
 208   abstract public Explanation explain(Weight weight, int doc) throws IOException;
 209   abstract public TopFieldDocs search(Weight weight, Filter filter, int n, Sort sort) throws IOException;
 210   /* End patch for GCJ bug #15411. */
 211 }