From 73b462a8230e35233c2cbf7b99d8a66d1841e32a Mon Sep 17 00:00:00 2001
From: Michael McCandless <mikemccand@apache.org>
Date: Tue, 23 Jun 2009 10:48:55 +0000
Subject: [PATCH] add javadocs NOTE stating that the core collectors
 pre-allocate the full array[numHits] up front

git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@787628 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/lucene/search/FieldValueHitQueue.java     | 3 +++
 src/java/org/apache/lucene/search/HitQueue.java          | 3 +++
 src/java/org/apache/lucene/search/TopFieldCollector.java | 7 ++++++-
 .../org/apache/lucene/search/TopScoreDocCollector.java   | 5 +++++
 src/java/org/apache/lucene/util/PriorityQueue.java       | 9 +++++++--
 5 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/src/java/org/apache/lucene/search/FieldValueHitQueue.java b/src/java/org/apache/lucene/search/FieldValueHitQueue.java
index 5d330d654a4..13a191137ad 100644
--- a/src/java/org/apache/lucene/search/FieldValueHitQueue.java
+++ b/src/java/org/apache/lucene/search/FieldValueHitQueue.java
@@ -173,6 +173,9 @@ public abstract class FieldValueHitQueue extends PriorityQueue {
   /**
    * Creates a hit queue sorted by the given list of fields.
    * 
+   * <p><b>NOTE</b>: The instances returned by this method
+   * pre-allocate a full array of length <code>numHits</code>.
+   * 
    * @param fields
    *          SortField array we are sorting by in priority order (highest
    *          priority first); cannot be <code>null</code> or empty
diff --git a/src/java/org/apache/lucene/search/HitQueue.java b/src/java/org/apache/lucene/search/HitQueue.java
index 24f3d635f95..3aa12dd468a 100644
--- a/src/java/org/apache/lucene/search/HitQueue.java
+++ b/src/java/org/apache/lucene/search/HitQueue.java
@@ -53,6 +53,9 @@ final class HitQueue extends PriorityQueue {
    * }
    * </pre>
    * 
+   * <p><b>NOTE</b>: This class pre-allocate a full array of
+   * length <code>size</code>.
+   * 
    * @param size
    *          the requested size of this queue.
    * @param prePopulate
diff --git a/src/java/org/apache/lucene/search/TopFieldCollector.java b/src/java/org/apache/lucene/search/TopFieldCollector.java
index 1ffe0587b20..88d814f2230 100644
--- a/src/java/org/apache/lucene/search/TopFieldCollector.java
+++ b/src/java/org/apache/lucene/search/TopFieldCollector.java
@@ -810,7 +810,12 @@ public abstract class TopFieldCollector extends TopDocsCollector {
   }
 
   /**
-   * Creates a new {@link TopFieldCollector} from the given arguments.
+   * Creates a new {@link TopFieldCollector} from the given
+   * arguments.
+   *
+   * <p><b>NOTE</b>: The instances returned by this method
+   * pre-allocate a full array of length
+   * <code>numHits</code>.
    * 
    * @param sort
    *          the sort criteria (SortFields).
diff --git a/src/java/org/apache/lucene/search/TopScoreDocCollector.java b/src/java/org/apache/lucene/search/TopScoreDocCollector.java
index ec9a1f657f3..9b049f3f4fd 100644
--- a/src/java/org/apache/lucene/search/TopScoreDocCollector.java
+++ b/src/java/org/apache/lucene/search/TopScoreDocCollector.java
@@ -80,6 +80,11 @@ public abstract class TopScoreDocCollector extends TopDocsCollector {
    * Creates a new {@link TopScoreDocCollector} given the number of hits to
    * collect and whether documents are scored in order by the input
    * {@link Scorer} to {@link #setScorer(Scorer)}.
+   *
+   * <p><b>NOTE</b>: The instances returned by this method
+   * pre-allocate a full array of length
+   * <code>numHits</code>, and fill the array with sentinel
+   * objects.
    */
   public static TopScoreDocCollector create(int numHits, boolean docsScoredInOrder) {
     
diff --git a/src/java/org/apache/lucene/util/PriorityQueue.java b/src/java/org/apache/lucene/util/PriorityQueue.java
index e12e3ec5076..2adcb77d301 100644
--- a/src/java/org/apache/lucene/util/PriorityQueue.java
+++ b/src/java/org/apache/lucene/util/PriorityQueue.java
@@ -18,8 +18,13 @@ package org.apache.lucene.util;
  */
 
 /** A PriorityQueue maintains a partial ordering of its elements such that the
-  least element can always be found in constant time.  Put()'s and pop()'s
-  require log(size) time. */
+ * least element can always be found in constant time.  Put()'s and pop()'s
+ * require log(size) time.
+ *
+ * <p><b>NOTE</b>: This class pre-allocates a full array of
+ * length <code>maxSize+1</code>, in {@link #initialize}.
+  * 
+*/
 public abstract class PriorityQueue {
   private int size;
   private int maxSize;