Deprecate FacetsCollector#search utility methods (#13737)

These can now be replaced by the corresponding methods added to FacetsCollectorManager that accept a FacetsCollectorManager as last argument in place of a Collector Relates to #11041
apache · Sep 7, 2024 · 04d0170 · 04d0170
1 parent ef5d0f2
commit 04d0170
Show file tree

Hide file tree

Showing 18 changed files with 327 additions and 60 deletions.
diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txt
@@ -24,6 +24,9 @@ API Changes
 * GITHUB#13568: Add DrillSideways#search method that supports any CollectorManagers for drill-sideways dimensions
   or drill-down. (Egor Potemkin)
 
+* GITHUB#13737: Deprecate the FacetsCollector#search utility methods and add new corresponding method to
+  FacetsCollectorManager that accept a FacetsCollectorManager as last argument in place of a Collector. (Luca Cavanna)
+
 New Features
 ---------------------
 

diff --git a/lucene/demo/src/java/org/apache/lucene/demo/facet/AssociationsFacetsExample.java b/lucene/demo/src/java/org/apache/lucene/demo/facet/AssociationsFacetsExample.java
@@ -25,6 +25,7 @@
 import org.apache.lucene.facet.FacetResult;
 import org.apache.lucene.facet.Facets;
 import org.apache.lucene.facet.FacetsCollector;
+import org.apache.lucene.facet.FacetsCollectorManager;
 import org.apache.lucene.facet.FacetsConfig;
 import org.apache.lucene.facet.LabelAndValue;
 import org.apache.lucene.facet.taxonomy.AssociationAggregationFunction;
@@ -97,12 +98,13 @@ private List<FacetResult> sumAssociations() throws IOException {
     IndexSearcher searcher = new IndexSearcher(indexReader);
     TaxonomyReader taxoReader = new DirectoryTaxonomyReader(taxoDir);
 
-    FacetsCollector fc = new FacetsCollector();
-
     // MatchAllDocsQuery is for "browsing" (counts facets
     // for all non-deleted docs in the index); normally
     // you'd use a "normal" query:
-    FacetsCollector.search(searcher, new MatchAllDocsQuery(), 10, fc);
+    FacetsCollectorManager.FacetsResult facetsResult =
+        FacetsCollectorManager.search(
+            searcher, new MatchAllDocsQuery(), 10, new FacetsCollectorManager());
+    FacetsCollector fc = facetsResult.facetsCollector();
 
     Facets tags =
         new TaxonomyFacetIntAssociations(
@@ -133,8 +135,8 @@ private FacetResult drillDown() throws IOException {
 
     // Now user drills down on Publish Date/2010:
     q.add("tags", "solr");
-    FacetsCollector fc = new FacetsCollector();
-    FacetsCollector.search(searcher, q, 10, fc);
+    FacetsCollectorManager fcm = new FacetsCollectorManager();
+    FacetsCollector fc = FacetsCollectorManager.search(searcher, q, 10, fcm).facetsCollector();
 
     // Retrieve results
     Facets facets =

diff --git a/lucene/demo/src/java/org/apache/lucene/demo/facet/ExpressionAggregationFacetsExample.java b/lucene/demo/src/java/org/apache/lucene/demo/facet/ExpressionAggregationFacetsExample.java
@@ -30,6 +30,7 @@
 import org.apache.lucene.facet.FacetResult;
 import org.apache.lucene.facet.Facets;
 import org.apache.lucene.facet.FacetsCollector;
+import org.apache.lucene.facet.FacetsCollectorManager;
 import org.apache.lucene.facet.FacetsConfig;
 import org.apache.lucene.facet.taxonomy.AssociationAggregationFunction;
 import org.apache.lucene.facet.taxonomy.TaxonomyFacetFloatAssociations;
@@ -97,12 +98,13 @@ private FacetResult search() throws IOException, ParseException {
         DoubleValuesSource.fromLongField("popularity")); // the value of the 'popularity' field
 
     // Aggregates the facet values
-    FacetsCollector fc = new FacetsCollector(true);
+    FacetsCollectorManager fcm = new FacetsCollectorManager(true);
 
     // MatchAllDocsQuery is for "browsing" (counts facets
     // for all non-deleted docs in the index); normally
     // you'd use a "normal" query:
-    FacetsCollector.search(searcher, new MatchAllDocsQuery(), 10, fc);
+    FacetsCollector fc =
+        FacetsCollectorManager.search(searcher, new MatchAllDocsQuery(), 10, fcm).facetsCollector();
 
     // Retrieve results
     Facets facets =

diff --git a/lucene/demo/src/java/org/apache/lucene/demo/facet/MultiCategoryListsFacetsExample.java b/lucene/demo/src/java/org/apache/lucene/demo/facet/MultiCategoryListsFacetsExample.java
@@ -25,6 +25,7 @@
 import org.apache.lucene.facet.FacetResult;
 import org.apache.lucene.facet.Facets;
 import org.apache.lucene.facet.FacetsCollector;
+import org.apache.lucene.facet.FacetsCollectorManager;
 import org.apache.lucene.facet.FacetsConfig;
 import org.apache.lucene.facet.taxonomy.FastTaxonomyFacetCounts;
 import org.apache.lucene.facet.taxonomy.TaxonomyReader;
@@ -97,12 +98,13 @@ private List<FacetResult> search() throws IOException {
     IndexSearcher searcher = new IndexSearcher(indexReader);
     TaxonomyReader taxoReader = new DirectoryTaxonomyReader(taxoDir);
 
-    FacetsCollector fc = new FacetsCollector();
+    FacetsCollectorManager fcm = new FacetsCollectorManager();
 
     // MatchAllDocsQuery is for "browsing" (counts facets
     // for all non-deleted docs in the index); normally
     // you'd use a "normal" query:
-    FacetsCollector.search(searcher, new MatchAllDocsQuery(), 10, fc);
+    FacetsCollector fc =
+        FacetsCollectorManager.search(searcher, new MatchAllDocsQuery(), 10, fcm).facetsCollector();
 
     // Retrieve results
     List<FacetResult> results = new ArrayList<>();

diff --git a/lucene/demo/src/java/org/apache/lucene/demo/facet/RangeFacetsExample.java b/lucene/demo/src/java/org/apache/lucene/demo/facet/RangeFacetsExample.java
@@ -27,6 +27,7 @@
 import org.apache.lucene.facet.FacetResult;
 import org.apache.lucene.facet.Facets;
 import org.apache.lucene.facet.FacetsCollector;
+import org.apache.lucene.facet.FacetsCollectorManager;
 import org.apache.lucene.facet.FacetsConfig;
 import org.apache.lucene.facet.range.LongRange;
 import org.apache.lucene.facet.range.LongRangeFacetCounts;
@@ -86,13 +87,13 @@ private FacetsConfig getConfig() {
   /** User runs a query and counts facets. */
   public FacetResult search() throws IOException {
 
-    // Aggregates the facet counts
-    FacetsCollector fc = new FacetsCollector();
-
     // MatchAllDocsQuery is for "browsing" (counts facets
     // for all non-deleted docs in the index); normally
     // you'd use a "normal" query:
-    FacetsCollector.search(searcher, new MatchAllDocsQuery(), 10, fc);
+    FacetsCollector fc =
+        FacetsCollectorManager.search(
+                searcher, new MatchAllDocsQuery(), 10, new FacetsCollectorManager())
+            .facetsCollector();
 
     Facets facets = new LongRangeFacetCounts("timestamp", fc, PAST_HOUR, PAST_SIX_HOURS, PAST_DAY);
     return facets.getTopChildren(10, "timestamp");

diff --git a/lucene/demo/src/java/org/apache/lucene/demo/facet/SimpleFacetsExample.java b/lucene/demo/src/java/org/apache/lucene/demo/facet/SimpleFacetsExample.java
@@ -99,12 +99,13 @@ List<FacetResult> facetsWithSearch() throws IOException {
     IndexSearcher searcher = new IndexSearcher(indexReader);
     TaxonomyReader taxoReader = new DirectoryTaxonomyReader(taxoDir);
 
-    FacetsCollector fc = new FacetsCollector();
+    FacetsCollectorManager fcm = new FacetsCollectorManager();
 
     // MatchAllDocsQuery is for "browsing" (counts facets
     // for all non-deleted docs in the index); normally
     // you'd use a "normal" query:
-    FacetsCollector.search(searcher, new MatchAllDocsQuery(), 10, fc);
+    FacetsCollector fc =
+        FacetsCollectorManager.search(searcher, new MatchAllDocsQuery(), 10, fcm).facetsCollector();
 
     // Retrieve results
     List<FacetResult> results = new ArrayList<>();
@@ -156,8 +157,8 @@ FacetResult drillDown() throws IOException {
 
     // Now user drills down on Publish Date/2010:
     q.add("Publish Date", "2010");
-    FacetsCollector fc = new FacetsCollector();
-    FacetsCollector.search(searcher, q, 10, fc);
+    FacetsCollectorManager fcm = new FacetsCollectorManager();
+    FacetsCollector fc = FacetsCollectorManager.search(searcher, q, 10, fcm).facetsCollector();
 
     // Retrieve results
     Facets facets = new FastTaxonomyFacetCounts(taxoReader, config, fc);

diff --git a/lucene/demo/src/java/org/apache/lucene/demo/facet/SimpleSortedSetFacetsExample.java b/lucene/demo/src/java/org/apache/lucene/demo/facet/SimpleSortedSetFacetsExample.java
@@ -25,6 +25,7 @@
 import org.apache.lucene.facet.FacetResult;
 import org.apache.lucene.facet.Facets;
 import org.apache.lucene.facet.FacetsCollector;
+import org.apache.lucene.facet.FacetsCollectorManager;
 import org.apache.lucene.facet.FacetsConfig;
 import org.apache.lucene.facet.sortedset.DefaultSortedSetDocValuesReaderState;
 import org.apache.lucene.facet.sortedset.SortedSetDocValuesFacetCounts;
@@ -92,12 +93,13 @@ private List<FacetResult> search() throws IOException {
         new DefaultSortedSetDocValuesReaderState(indexReader, config);
 
     // Aggregates the facet counts
-    FacetsCollector fc = new FacetsCollector();
+    FacetsCollectorManager fcm = new FacetsCollectorManager();
 
     // MatchAllDocsQuery is for "browsing" (counts facets
     // for all non-deleted docs in the index); normally
     // you'd use a "normal" query:
-    FacetsCollector.search(searcher, new MatchAllDocsQuery(), 10, fc);
+    FacetsCollector fc =
+        FacetsCollectorManager.search(searcher, new MatchAllDocsQuery(), 10, fcm).facetsCollector();
 
     // Retrieve results
     Facets facets = new SortedSetDocValuesFacetCounts(state, fc);
@@ -120,8 +122,8 @@ private FacetResult drillDown() throws IOException {
     // Now user drills down on Publish Year/2010:
     DrillDownQuery q = new DrillDownQuery(config);
     q.add("Publish Year", "2010");
-    FacetsCollector fc = new FacetsCollector();
-    FacetsCollector.search(searcher, q, 10, fc);
+    FacetsCollectorManager fcm = new FacetsCollectorManager();
+    FacetsCollector fc = FacetsCollectorManager.search(searcher, q, 10, fcm).facetsCollector();
 
     // Retrieve results
     Facets facets = new SortedSetDocValuesFacetCounts(state, fc);

diff --git a/lucene/demo/src/java/org/apache/lucene/demo/facet/StringValueFacetCountsExample.java b/lucene/demo/src/java/org/apache/lucene/demo/facet/StringValueFacetCountsExample.java
@@ -27,6 +27,7 @@
 import org.apache.lucene.facet.FacetResult;
 import org.apache.lucene.facet.Facets;
 import org.apache.lucene.facet.FacetsCollector;
+import org.apache.lucene.facet.FacetsCollectorManager;
 import org.apache.lucene.facet.FacetsConfig;
 import org.apache.lucene.facet.StringDocValuesReaderState;
 import org.apache.lucene.facet.StringValueFacetCounts;
@@ -96,12 +97,13 @@ private List<FacetResult> search() throws IOException {
         new StringDocValuesReaderState(indexReader, "Publish Year");
 
     // Aggregates the facet counts
-    FacetsCollector fc = new FacetsCollector();
+    FacetsCollectorManager fcm = new FacetsCollectorManager();
 
     // MatchAllDocsQuery is for "browsing" (counts facets
     // for all non-deleted docs in the index); normally
     // you'd use a "normal" query:
-    FacetsCollector.search(searcher, new MatchAllDocsQuery(), 10, fc);
+    FacetsCollector fc =
+        FacetsCollectorManager.search(searcher, new MatchAllDocsQuery(), 10, fcm).facetsCollector();
 
     // Retrieve results
     Facets authorFacets = new StringValueFacetCounts(authorState, fc);

diff --git a/lucene/demo/src/java/org/apache/lucene/demo/facet/package-info.java b/lucene/demo/src/java/org/apache/lucene/demo/facet/package-info.java
@@ -198,9 +198,9 @@
  * org.apache.lucene.search.Collector}, and as such can be passed to the search() method of Lucene's
  * {@link org.apache.lucene.search.IndexSearcher}. In case the application also needs to collect
  * documents (in addition to accumulating/collecting facets), you can use one of {@link
- * org.apache.lucene.facet.FacetsCollector#search(org.apache.lucene.search.IndexSearcher,
- * org.apache.lucene.search.Query, int, org.apache.lucene.search.Collector)
- * FacetsCollector.search(...)} utility methods.
+ * org.apache.lucene.facet.FacetsCollectorManager#search(org.apache.lucene.search.IndexSearcher,
+ * org.apache.lucene.search.Query, int, org.apache.lucene.facet.FacetsCollectorManager)
+ * FacetsCollectorManager.search(...)} utility methods.
  *
  * <p>There is a facets collecting code example in {@link
  * org.apache.lucene.demo.facet.SimpleFacetsExample#facetsWithSearch()}, see <a

diff --git a/lucene/facet/src/java/org/apache/lucene/facet/FacetsCollector.java b/lucene/facet/src/java/org/apache/lucene/facet/FacetsCollector.java
@@ -155,13 +155,25 @@ public void finish() throws IOException {
     context = null;
   }
 
-  /** Utility method, to search and also collect all hits into the provided {@link Collector}. */
+  /**
+   * Utility method, to search and also collect all hits into the provided {@link Collector}.
+   *
+   * @deprecated use {@link FacetsCollectorManager#search(IndexSearcher, Query, int,
+   *     FacetsCollectorManager)} instead.
+   */
+  @Deprecated
   public static TopDocs search(IndexSearcher searcher, Query q, int n, Collector fc)
       throws IOException {
     return doSearch(searcher, null, q, n, null, false, fc);
   }
 
-  /** Utility method, to search and also collect all hits into the provided {@link Collector}. */
+  /**
+   * Utility method, to search and also collect all hits into the provided {@link Collector}.
+   *
+   * @deprecated use {@link FacetsCollectorManager#search(IndexSearcher, Query, int, Sort,
+   *     FacetsCollectorManager)} instead.
+   */
+  @Deprecated
   public static TopFieldDocs search(IndexSearcher searcher, Query q, int n, Sort sort, Collector fc)
       throws IOException {
     if (sort == null) {
@@ -170,7 +182,13 @@ public static TopFieldDocs search(IndexSearcher searcher, Query q, int n, Sort s
     return (TopFieldDocs) doSearch(searcher, null, q, n, sort, false, fc);
   }
 
-  /** Utility method, to search and also collect all hits into the provided {@link Collector}. */
+  /**
+   * Utility method, to search and also collect all hits into the provided {@link Collector}.
+   *
+   * @deprecated use {@link FacetsCollectorManager#search(IndexSearcher, Query, int, Sort, boolean,
+   *     FacetsCollectorManager)} instead.
+   */
+  @Deprecated
   public static TopFieldDocs search(
       IndexSearcher searcher, Query q, int n, Sort sort, boolean doDocScores, Collector fc)
       throws IOException {
@@ -180,13 +198,25 @@ public static TopFieldDocs search(
     return (TopFieldDocs) doSearch(searcher, null, q, n, sort, doDocScores, fc);
   }
 
-  /** Utility method, to search and also collect all hits into the provided {@link Collector}. */
+  /**
+   * Utility method, to search and also collect all hits into the provided {@link Collector}.
+   *
+   * @deprecated use {@link FacetsCollectorManager#searchAfter(IndexSearcher, ScoreDoc, Query, int,
+   *     FacetsCollectorManager)} instead.
+   */
+  @Deprecated
   public static TopDocs searchAfter(
       IndexSearcher searcher, ScoreDoc after, Query q, int n, Collector fc) throws IOException {
     return doSearch(searcher, after, q, n, null, false, fc);
   }
 
-  /** Utility method, to search and also collect all hits into the provided {@link Collector}. */
+  /**
+   * Utility method, to search and also collect all hits into the provided {@link Collector}.
+   *
+   * @deprecated use {@link FacetsCollectorManager#searchAfter(IndexSearcher, ScoreDoc, Query, int,
+   *     Sort, FacetsCollectorManager)} instead.
+   */
+  @Deprecated
   public static TopDocs searchAfter(
       IndexSearcher searcher, ScoreDoc after, Query q, int n, Sort sort, Collector fc)
       throws IOException {
@@ -196,7 +226,13 @@ public static TopDocs searchAfter(
     return doSearch(searcher, after, q, n, sort, false, fc);
   }
 
-  /** Utility method, to search and also collect all hits into the provided {@link Collector}. */
+  /**
+   * Utility method, to search and also collect all hits into the provided {@link Collector}.
+   *
+   * @deprecated use {@link FacetsCollectorManager#searchAfter(IndexSearcher, ScoreDoc, Query, int,
+   *     Sort, boolean, FacetsCollectorManager)} instead.
+   */
+  @Deprecated
   public static TopDocs searchAfter(
       IndexSearcher searcher,
       ScoreDoc after,