lucene-java-3.5.0/lucene/src/java/org/apache/lucene/search/TopDocsCollector.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
  21 import org.apache.lucene.util.PriorityQueue;
  22
  23 /**
  24  * A base class for all collectors that return a {@link TopDocs} output. This
  25  * collector allows easy extension by providing a single constructor which
  26  * accepts a {@link PriorityQueue} as well as protected members for that
  27  * priority queue and a counter of the number of total hits.<br>
  28  * Extending classes can override any of the methods to provide their own
  29  * implementation, as well as avoid the use of the priority queue entirely by
  30  * passing null to {@link #TopDocsCollector(PriorityQueue)}. In that case
  31  * however, you might want to consider overriding all methods, in order to avoid
  32  * a NullPointerException.
  33  */
  34 public abstract class TopDocsCollector<T extends ScoreDoc> extends Collector {
  35
  36   // This is used in case topDocs() is called with illegal parameters, or there
  37   // simply aren't (enough) results.
  38   protected static final TopDocs EMPTY_TOPDOCS = new TopDocs(0, new ScoreDoc[0], Float.NaN);
  39
  40   /**
  41    * The priority queue which holds the top documents. Note that different
  42    * implementations of PriorityQueue give different meaning to 'top documents'.
  43    * HitQueue for example aggregates the top scoring documents, while other PQ
  44    * implementations may hold documents sorted by other criteria.
  45    */
  46   protected PriorityQueue<T> pq;
  47
  48   /** The total number of documents that the collector encountered. */
  49   protected int totalHits;
  50
  51   protected TopDocsCollector(PriorityQueue<T> pq) {
  52     this.pq = pq;
  53   }
  54
  55   /**
  56    * Populates the results array with the ScoreDoc instances. This can be
  57    * overridden in case a different ScoreDoc type should be returned.
  58    */
  59   protected void populateResults(ScoreDoc[] results, int howMany) {
  60     for (int i = howMany - 1; i >= 0; i--) {
  61       results[i] = pq.pop();
  62     }
  63   }
  64
  65   /**
  66    * Returns a {@link TopDocs} instance containing the given results. If
  67    * <code>results</code> is null it means there are no results to return,
  68    * either because there were 0 calls to collect() or because the arguments to
  69    * topDocs were invalid.
  70    */
  71   protected TopDocs newTopDocs(ScoreDoc[] results, int start) {
  72     return results == null ? EMPTY_TOPDOCS : new TopDocs(totalHits, results);
  73   }
  74
  75   /** The total number of documents that matched this query. */
  76   public int getTotalHits() {
  77     return totalHits;
  78   }
  79
  80   /** The number of valid PQ entries */
  81   protected int topDocsSize() {
  82     // In case pq was populated with sentinel values, there might be less
  83     // results than pq.size(). Therefore return all results until either
  84     // pq.size() or totalHits.
  85     return totalHits < pq.size() ? totalHits : pq.size();
  86   }
  87
  88   /** Returns the top docs that were collected by this collector. */
  89   public TopDocs topDocs() {
  90     // In case pq was populated with sentinel values, there might be less
  91     // results than pq.size(). Therefore return all results until either
  92     // pq.size() or totalHits.
  93     return topDocs(0, topDocsSize());
  94   }
  95
  96   /**
  97    * Returns the documents in the rage [start .. pq.size()) that were collected
  98    * by this collector. Note that if start >= pq.size(), an empty TopDocs is
  99    * returned.<br>
 100    * This method is convenient to call if the application always asks for the
 101    * last results, starting from the last 'page'.<br>
 102    * <b>NOTE:</b> you cannot call this method more than once for each search
 103    * execution. If you need to call it more than once, passing each time a
 104    * different <code>start</code>, you should call {@link #topDocs()} and work
 105    * with the returned {@link TopDocs} object, which will contain all the
 106    * results this search execution collected.
 107    */
 108   public TopDocs topDocs(int start) {
 109     // In case pq was populated with sentinel values, there might be less
 110     // results than pq.size(). Therefore return all results until either
 111     // pq.size() or totalHits.
 112     return topDocs(start, topDocsSize());
 113   }
 114
 115   /**
 116    * Returns the documents in the rage [start .. start+howMany) that were
 117    * collected by this collector. Note that if start >= pq.size(), an empty
 118    * TopDocs is returned, and if pq.size() - start &lt; howMany, then only the
 119    * available documents in [start .. pq.size()) are returned.<br>
 120    * This method is useful to call in case pagination of search results is
 121    * allowed by the search application, as well as it attempts to optimize the
 122    * memory used by allocating only as much as requested by howMany.<br>
 123    * <b>NOTE:</b> you cannot call this method more than once for each search
 124    * execution. If you need to call it more than once, passing each time a
 125    * different range, you should call {@link #topDocs()} and work with the
 126    * returned {@link TopDocs} object, which will contain all the results this
 127    * search execution collected.
 128    */
 129   public TopDocs topDocs(int start, int howMany) {
 130
 131     // In case pq was populated with sentinel values, there might be less
 132     // results than pq.size(). Therefore return all results until either
 133     // pq.size() or totalHits.
 134     int size = topDocsSize();
 135
 136     // Don't bother to throw an exception, just return an empty TopDocs in case
 137     // the parameters are invalid or out of range.
 138     // TODO: shouldn't we throw IAE if apps give bad params here so they dont
 139     // have sneaky silent bugs?
 140     if (start < 0 || start >= size || howMany <= 0) {
 141       return newTopDocs(null, start);
 142     }
 143
 144     // We know that start < pqsize, so just fix howMany.
 145     howMany = Math.min(size - start, howMany);
 146     ScoreDoc[] results = new ScoreDoc[howMany];
 147
 148     // pq's pop() returns the 'least' element in the queue, therefore need
 149     // to discard the first ones, until we reach the requested range.
 150     // Note that this loop will usually not be executed, since the common usage
 151     // should be that the caller asks for the last howMany results. However it's
 152     // needed here for completeness.
 153     for (int i = pq.size() - start - howMany; i > 0; i--) { pq.pop(); }
 154
 155     // Get the requested results from pq.
 156     populateResults(results, howMany);
 157
 158     return newTopDocs(results, start);
 159   }
 160
 161 }