--- /dev/null
+package org.apache.lucene.facet.search;
+
+import java.io.IOException;
+
+import org.apache.lucene.facet.search.params.FacetRequest;
+import org.apache.lucene.facet.search.results.FacetResult;
+import org.apache.lucene.facet.search.results.FacetResultNode;
+import org.apache.lucene.facet.search.results.IntermediateFacetResult;
+import org.apache.lucene.facet.taxonomy.TaxonomyReader;
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Handler for facet results.
+ * <p>
+ * The facet results handler provided by the {@link FacetRequest} to
+ * a {@link FacetsAccumulator}.
+ * <p>
+ * First it is used by {@link FacetsAccumulator} to obtain a temporary
+ * facet result for each partition and to merge results of several partitions.
+ * <p>
+ * Later the accumulator invokes the handler to render the results, creating
+ * {@link FacetResult} objects.
+ * <p>
+ * Last the accumulator invokes the handler to label final results.
+ *
+ * @lucene.experimental
+ */
+public abstract class FacetResultsHandler {
+
+ /** Taxonomy for which facets are handled */
+ protected final TaxonomyReader taxonomyReader;
+
+ /**
+ * Facet request served by this handler.
+ */
+ protected final FacetRequest facetRequest;
+
+ /**
+ * Create a faceted search handler.
+ * @param taxonomyReader See {@link #getTaxonomyReader()}.
+ * @param facetRequest See {@link #getFacetRequest()}.
+ */
+ public FacetResultsHandler(TaxonomyReader taxonomyReader,
+ FacetRequest facetRequest) {
+ this.taxonomyReader = taxonomyReader;
+ this.facetRequest = facetRequest;
+ }
+
+ /**
+ * Fetch results of a single partition, given facet arrays for that partition,
+ * and based on the matching documents and faceted search parameters.
+ *
+ * @param arrays
+ * facet arrays for the certain partition
+ * @param offset
+ * offset in input arrays where partition starts
+ * @return temporary facet result, potentially, to be passed back to
+ * <b>this</b> result handler for merging, or <b>null</b> in case that
+ * constructor parameter, <code>facetRequest</code>, requests an
+ * illegal FacetResult, like, e.g., a root node category path that
+ * does not exist in constructor parameter <code>taxonomyReader</code>
+ * .
+ * @throws IOException
+ * on error
+ */
+ public abstract IntermediateFacetResult fetchPartitionResult(FacetArrays arrays, int offset) throws IOException;
+
+ /**
+ * Merge results of several facet partitions. Logic of the merge is undefined
+ * and open for interpretations. For example, a merge implementation could
+ * keep top K results. Passed {@link IntermediateFacetResult} must be ones
+ * that were created by this handler otherwise a {@link ClassCastException} is
+ * thrown. In addition, all passed {@link IntermediateFacetResult} must have
+ * the same {@link FacetRequest} otherwise an {@link IllegalArgumentException}
+ * is thrown.
+ *
+ * @param tmpResults one or more temporary results created by <b>this</b>
+ * handler.
+ * @return temporary facet result that represents to union, as specified by
+ * <b>this</b> handler, of the input temporary facet results.
+ * @throws IOException on error.
+ * @throws ClassCastException if the temporary result passed was not created
+ * by this handler
+ * @throws IllegalArgumentException if passed <code>facetResults</code> do not
+ * have the same {@link FacetRequest}
+ * @see IntermediateFacetResult#getFacetRequest()
+ */
+ public abstract IntermediateFacetResult mergeResults(IntermediateFacetResult... tmpResults)
+ throws IOException, ClassCastException, IllegalArgumentException;
+
+ /**
+ * Create a facet result from the temporary result.
+ * @param tmpResult temporary result to be rendered as a {@link FacetResult}
+ * @throws IOException on error.
+ */
+ public abstract FacetResult renderFacetResult(IntermediateFacetResult tmpResult) throws IOException ;
+
+ /**
+ * Perform any rearrangement as required on a facet result that has changed after
+ * it was rendered.
+ * <P>
+ * Possible use case: a sampling facets accumulator invoked another
+ * other facets accumulator on a sample set of documents, obtained
+ * rendered facet results, fixed their counts, and now it is needed
+ * to sort the results differently according to the fixed counts.
+ * @param facetResult result to be rearranged.
+ * @see FacetResultNode#setValue(double)
+ */
+ public abstract FacetResult rearrangeFacetResult(FacetResult facetResult);
+
+ /**
+ * Label results according to settings in {@link FacetRequest},
+ * such as {@link FacetRequest#getNumLabel()}.
+ * Usually invoked by {@link FacetsAccumulator#accumulate(ScoredDocIDs)}
+ * @param facetResult facet result to be labeled.
+ * @throws IOException on error
+ */
+ public abstract void labelResult (FacetResult facetResult) throws IOException;
+
+ /** Return taxonomy reader used for current facets accumulation operation. */
+ public final TaxonomyReader getTaxonomyReader() {
+ return this.taxonomyReader;
+ }
+
+ /** Return the facet request served by this handler. */
+ public final FacetRequest getFacetRequest() {
+ return this.facetRequest;
+ }
+
+ /**
+ * Check if an array contains the partition which contains ordinal
+ *
+ * @param ordinal
+ * checked facet
+ * @param facetArrays
+ * facet arrays for the certain partition
+ * @param offset
+ * offset in input arrays where partition starts
+ */
+ protected boolean isSelfPartition (int ordinal, FacetArrays facetArrays, int offset) {
+ int partitionSize = facetArrays.getArraysLength();
+ return ordinal / partitionSize == offset / partitionSize;
+ }
+
+}
fnp / pylucene.git / blobdiff