## org.apache.lucene.facet.search
Class FacetResultsHandler

    java.lang.Object
      org.apache.lucene.facet.search.FacetResultsHandler

Direct Known Subclasses:
  TopKFacetResultsHandler, TopKInEachNodeHandler

    public abstract class FacetResultsHandler

extends Object

Handler for facet results.

The facet results handler provided by the `FacetRequest` to a `FacetsAccumulator`.

First it is used by `FacetsAccumulator` to obtain a temporary facet result for each partition and to merge results of several partitions.

Later the accumulator invokes the handler to render the results, creating `FacetResult` objects.

Last the accumulator invokes the handler to label final results.

WARNING: This API is experimental and might change in incompatible ways in the next release.

Field Summary
`protected FacetRequest` `facetRequest` Facet request served by this handler.
`protected TaxonomyReader` `taxonomyReader` Taxonomy for which facets are handled

Constructor Summary
`FacetResultsHandler(TaxonomyReader taxonomyReader, FacetRequest facetRequest)` Create a faceted search handler.

Method Summary
`abstract IntermediateFacetResult` `fetchPartitionResult(FacetArrays arrays, int offset)` Fetch results of a single partition, given facet arrays for that partition, and based on the matching documents and faceted search parameters.
`FacetRequest` `getFacetRequest()` Return the facet request served by this handler.
`TaxonomyReader` `getTaxonomyReader()` Return taxonomy reader used for current facets accumulation operation.
`protected boolean` `isSelfPartition(int ordinal, FacetArrays facetArrays, int offset)` Check if an array contains the partition which contains ordinal
`abstract void` `labelResult(FacetResult facetResult)` Label results according to settings in `FacetRequest`, such as `FacetRequest.getNumLabel()`.
`abstract IntermediateFacetResult` `mergeResults(IntermediateFacetResult... tmpResults)` Merge results of several facet partitions.
`abstract FacetResult` `rearrangeFacetResult(FacetResult facetResult)` Perform any rearrangement as required on a facet result that has changed after it was rendered.
`abstract FacetResult` `renderFacetResult(IntermediateFacetResult tmpResult)` Create a facet result from the temporary result.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### taxonomyReader

    protected final TaxonomyReader taxonomyReader

  Taxonomy for which facets are handled

### facetRequest

    protected final FacetRequest facetRequest

  Facet request served by this handler.

Constructor Detail

### FacetResultsHandler

    public FacetResultsHandler(TaxonomyReader taxonomyReader,
                               FacetRequest facetRequest)

  Create a faceted search handler.

  Parameters:
    `taxonomyReader` - See `getTaxonomyReader()`.
    `facetRequest` - See `getFacetRequest()`.

Method Detail

### fetchPartitionResult

    public abstract IntermediateFacetResult fetchPartitionResult(FacetArrays arrays,
                                                                 int offset)
                                                          throws IOException

  Fetch results of a single partition, given facet arrays for that partition, and based on the matching documents and faceted search parameters.

  Parameters:
    `arrays` - facet arrays for the certain partition
    `offset` - offset in input arrays where partition starts
  Returns:
    temporary facet result, potentially, to be passed back to this result handler for merging, or null in case that constructor parameter, `facetRequest`, requests an illegal FacetResult, like, e.g., a root node category path that does not exist in constructor parameter `taxonomyReader` .
  Throws:
    `IOException` - on error

### mergeResults

    public abstract IntermediateFacetResult mergeResults(IntermediateFacetResult... tmpResults)
                                                  throws IOException,
                                                         ClassCastException,
                                                         IllegalArgumentException

  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 `IntermediateFacetResult` must be ones that were created by this handler otherwise a `ClassCastException` is thrown. In addition, all passed `IntermediateFacetResult` must have the same `FacetRequest` otherwise an `IllegalArgumentException` is thrown.

  Parameters:
    `tmpResults` - one or more temporary results created by this handler.
  Returns:
    temporary facet result that represents to union, as specified by this handler, of the input temporary facet results.
  Throws:
    `IOException` - on error.
    `ClassCastException` - if the temporary result passed was not created by this handler
    `IllegalArgumentException` - if passed `facetResults` do not have the same `FacetRequest`
  See Also:
    `IntermediateFacetResult.getFacetRequest()`

### renderFacetResult

    public abstract FacetResult renderFacetResult(IntermediateFacetResult tmpResult)
                                           throws IOException

  Create a facet result from the temporary result.

  Parameters:
    `tmpResult` - temporary result to be rendered as a `FacetResult`
  Throws:
    `IOException` - on error.

### rearrangeFacetResult

    public abstract FacetResult rearrangeFacetResult(FacetResult facetResult)

  Perform any rearrangement as required on a facet result that has changed after it was rendered.

  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.

  Parameters:
    `facetResult` - result to be rearranged.
  See Also:
    `FacetResultNode.setValue(double)`

### labelResult

    public abstract void labelResult(FacetResult facetResult)
                              throws IOException

  Label results according to settings in `FacetRequest`, such as `FacetRequest.getNumLabel()`. Usually invoked by `FacetsAccumulator.accumulate(ScoredDocIDs)`

  Parameters:
    `facetResult` - facet result to be labeled.
  Throws:
    `IOException` - on error

### getTaxonomyReader

    public final TaxonomyReader getTaxonomyReader()

  Return taxonomy reader used for current facets accumulation operation.

### getFacetRequest

    public final FacetRequest getFacetRequest()

  Return the facet request served by this handler.

### isSelfPartition

    protected boolean isSelfPartition(int ordinal,
                                      FacetArrays facetArrays,
                                      int offset)

  Check if an array contains the partition which contains ordinal

  Parameters:
    `ordinal` - checked facet
    `facetArrays` - facet arrays for the certain partition
    `offset` - offset in input arrays where partition starts