Remove unused public methods in AllGroupHeadsCollector

lucene/CHANGES.txt

@@ -321,6 +321,9 @@ API Changes
 
 * GITHUB#16363: Add API to use a custom `DictionarySuggester` instead of hardcoded `GeneratingSuggester`
 
+* GITHUB#16385: Remove unused public methods in AllGroupHeadsCollector.
+                Update grouping package info to use CollectorManager instead of Collector. (Binlong Gao)
+
 New Features
 ---------------------
 

lucene/grouping/src/java/org/apache/lucene/search/grouping/AllGroupHeadsCollector.java

@@ -20,7 +20,6 @@
 import java.util.Collection;
 import java.util.HashMap;
 import java.util.Map;
-import org.apache.lucene.index.IndexReader;
 import org.apache.lucene.index.LeafReaderContext;
 import org.apache.lucene.search.FieldComparator;
 import org.apache.lucene.search.LeafFieldComparator;
@@ -30,7 +29,6 @@
 import org.apache.lucene.search.SimpleCollector;
 import org.apache.lucene.search.Sort;
 import org.apache.lucene.search.SortField;
-import org.apache.lucene.util.FixedBitSet;
 
 /**
  * This collector specializes in collecting the most relevant document (group head) for each group
@@ -40,7 +38,7 @@
  *
  * @lucene.experimental
  */
-@SuppressWarnings({"unchecked", "rawtypes"})
+@SuppressWarnings({"rawtypes"})
 public abstract class AllGroupHeadsCollector<T> extends SimpleCollector {
 
   private final GroupSelector<T> groupSelector;
@@ -79,44 +77,6 @@ private AllGroupHeadsCollector(GroupSelector<T> selector, Sort sort) {
     this.compIDXEnd = this.reversed.length - 1;
   }
 
-  /**
-   * @param maxDoc The maxDoc of the top level {@link IndexReader}.
-   * @return a {@link FixedBitSet} containing all group heads.
-   */
-  public FixedBitSet retrieveGroupHeads(int maxDoc) {
-    FixedBitSet bitSet = new FixedBitSet(maxDoc);
-
-    Collection<? extends GroupHead<T>> groupHeads = getCollectedGroupHeads();
-    for (GroupHead groupHead : groupHeads) {
-      bitSet.set(groupHead.doc);
-    }
-
-    return bitSet;
-  }
-
-  /**
-   * @return an int array containing all group heads. The size of the array is equal to number of
-   *     collected unique groups.
-   */
-  public int[] retrieveGroupHeads() {
-    Collection<? extends GroupHead<T>> groupHeads = getCollectedGroupHeads();
-    int[] docHeads = new int[groupHeads.size()];
-
-    int i = 0;
-    for (GroupHead groupHead : groupHeads) {
-      docHeads[i++] = groupHead.doc;
-    }
-
-    return docHeads;
-  }
-
-  /**
-   * @return the number of group heads found for a query.
-   */
-  public int groupHeadsSize() {
-    return getCollectedGroupHeads().size();
-  }
-
   /**
    * Returns the collected group heads. Subsequent calls should return the same group heads.
    *

lucene/grouping/src/java/org/apache/lucene/search/grouping/package-info.java

@@ -47,13 +47,15 @@
  * </ul>
  *
  * <p>The implementation is two-pass: the first pass ({@link
- * org.apache.lucene.search.grouping.FirstPassGroupingCollector}) gathers the top groups, and the
- * second pass ({@link org.apache.lucene.search.grouping.SecondPassGroupingCollector}) gathers
- * documents within those groups. If the search is costly to run you may want to use the {@link
- * org.apache.lucene.search.CachingCollector} class, which caches hits and can (quickly) replay them
- * for the second pass. This way you only run the query once, but you pay a RAM cost to (briefly)
- * hold all hits. Results are returned as a {@link org.apache.lucene.search.grouping.TopGroups}
- * instance.
+ * org.apache.lucene.search.grouping.FirstPassGroupingCollectorManager}) gathers the top groups, and
+ * the second pass ({@link org.apache.lucene.search.grouping.TopGroupsCollectorManager}) gathers
+ * documents within those groups. Both passes use {@link org.apache.lucene.search.CollectorManager}
+ * to support concurrent (parallel) collection across segments. If the search is costly to run you
+ * may want to use the {@link org.apache.lucene.search.CachingCollectorManager} class, which wraps
+ * the first-pass manager and caches all collected documents (and optionally scores) per segment
+ * slice so they can be replayed into the second-pass manager without re-running the query. This way
+ * you only run the query once, but you pay a RAM cost to (briefly) hold all hits. Results are
+ * returned as a {@link org.apache.lucene.search.grouping.TopGroups} instance.
  *
  * <p>Groups are defined by {@link org.apache.lucene.search.grouping.GroupSelector} implementations:
  *
@@ -101,9 +103,9 @@
  *   }
  * </code></pre>
  *
- * <p>To use the single-pass <code>BlockGroupingCollector</code>, first, at indexing time, you must
- * ensure all docs in each group are added as a block, and you have some way to find the last
- * document of each group. One simple way to do this is to add a marker binary field:
+ * <p>To use the single-pass <code>BlockGroupingCollectorManager</code>, first, at indexing time,
+ * you must ensure all docs in each group are added as a block, and you have some way to find the
+ * last document of each group. One simple way to do this is to add a marker binary field:
  *
  * <pre><code class="language-java">
  *   // Create Documents from your source:
@@ -125,9 +127,18 @@
  *
  * <pre><code class="language-java">
  *   Query groupEndDocs = new TermQuery(new Term("groupEnd", "x"));
- *   BlockGroupingCollector c = new BlockGroupingCollector(groupSort, groupOffset+topNGroups, needsScores, groupEndDocs);
- *   s.search(new TermQuery(new Term("content", searchTerm)), c);
- *   TopGroups groupsResult = c.getTopGroups(withinGroupSort, groupOffset, docOffset, docOffset+docsPerGroup, fillFields);
+ *   Weight lastDocPerGroup = indexSearcher.createWeight(
+ *       indexSearcher.rewrite(groupEndDocs), ScoreMode.COMPLETE_NO_SCORES, 1);
+ *   BlockGroupingCollectorManager&lt;BytesRef&gt; manager = new BlockGroupingCollectorManager&lt;&gt;(
+ *       groupSort,
+ *       groupOffset,
+ *       topNGroups,
+ *       needsScores,
+ *       lastDocPerGroup,
+ *       withinGroupSort,
+ *       docOffset,
+ *       docsPerGroup);
+ *   TopGroups groupsResult = indexSearcher.search(new TermQuery(new Term("content", searchTerm)), manager);
  *
  *   // Render groupsResult...
  * </code></pre>
@@ -149,22 +160,24 @@
  * so if you need to present this value you'll have to separately retrieve it (for example using
  * stored fields, <code>FieldCache</code>, etc.).
  *
- * <p>Another collector is the <code>AllGroupHeadsCollector</code> that can be used to retrieve all
- * most relevant documents per group. Also known as group heads. This can be useful in situations
- * when one wants to compute group based facets / statistics on the complete query result. The
- * collector can be executed during the first or second phase. This collector can also be used with
- * the <code>GroupingSearch</code> convenience utility, but when if one only wants to compute the
- * most relevant documents per group it is better to just use the collector as done here below.
+ * <p>Another collector manager is the <code>AllGroupHeadsCollectorManager</code> that can be used
+ * to retrieve all most relevant documents per group. Also known as group heads. This can be useful
+ * in situations when one wants to compute group based facets / statistics on the complete query
+ * result. The manager supports concurrent collection and can also be used with the <code>
+ * GroupingSearch</code> convenience utility, but when one only wants to compute the most relevant
+ * documents per group it is better to just use the manager directly as done here below.
  *
  * <pre><code class="language-java">
- *   TermGroupSelector grouper = new TermGroupSelector(groupField);
- *   AllGroupHeadsCollector c = AllGroupHeadsCollector.newCollector(grouper, sortWithinGroup);
- *   s.search(new TermQuery(new Term("content", searchTerm)), c);
+ *   AllGroupHeadsCollectorManager&lt;BytesRef&gt; manager =
+ *       new AllGroupHeadsCollectorManager&lt;&gt;(
+ *           () -&gt; new TermGroupSelector(groupField), sortWithinGroup);
+ *   AllGroupHeadsCollectorManager.GroupHeadsResult result =
+ *       indexSearcher.search(new TermQuery(new Term("content", searchTerm)), manager);
  *   // Return all group heads as int array
- *   int[] groupHeadsArray = c.retrieveGroupHeads()
+ *   int[] groupHeadsArray = result.retrieveGroupHeads();
  *   // Return all group heads as FixedBitSet.
- *   int maxDoc = s.maxDoc();
- *   FixedBitSet groupHeadsBitSet = c.retrieveGroupHeads(maxDoc)
+ *   int maxDoc = indexSearcher.getIndexReader().maxDoc();
+ *   Bits groupHeadsBitSet = result.retrieveGroupHeads(maxDoc);
  * </code></pre>
  */
 package org.apache.lucene.search.grouping;