lucene-java-3.5.0/lucene/contrib/facet/src/java/org/apache/lucene/facet/search/FacetResultsHandler.java

   1 package org.apache.lucene.facet.search;
   2
   3 import java.io.IOException;
   4
   5 import org.apache.lucene.facet.search.params.FacetRequest;
   6 import org.apache.lucene.facet.search.results.FacetResult;
   7 import org.apache.lucene.facet.search.results.FacetResultNode;
   8 import org.apache.lucene.facet.search.results.IntermediateFacetResult;
   9 import org.apache.lucene.facet.taxonomy.TaxonomyReader;
  10
  11 /**
  12  * Licensed to the Apache Software Foundation (ASF) under one or more
  13  * contributor license agreements.  See the NOTICE file distributed with
  14  * this work for additional information regarding copyright ownership.
  15  * The ASF licenses this file to You under the Apache License, Version 2.0
  16  * (the "License"); you may not use this file except in compliance with
  17  * the License.  You may obtain a copy of the License at
  18  *
  19  *     http://www.apache.org/licenses/LICENSE-2.0
  20  *
  21  * Unless required by applicable law or agreed to in writing, software
  22  * distributed under the License is distributed on an "AS IS" BASIS,
  23  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  24  * See the License for the specific language governing permissions and
  25  * limitations under the License.
  26  */
  27
  28 /**
  29  * Handler for facet results.
  30  * <p>
  31  * The facet results handler provided by the {@link FacetRequest} to
  32  * a {@link FacetsAccumulator}.
  33  * <p>
  34  * First it is used by {@link FacetsAccumulator} to obtain a temporary
  35  * facet result for each partition and to merge results of several partitions.
  36  * <p>
  37  * Later the accumulator invokes the handler to render the results, creating
  38  * {@link FacetResult} objects.
  39  * <p>
  40  * Last the accumulator invokes the handler to label final results.
  41  *
  42  * @lucene.experimental
  43  */
  44 public abstract class FacetResultsHandler {
  45
  46   /** Taxonomy for which facets are handled */
  47   protected final TaxonomyReader taxonomyReader;
  48
  49   /**
  50    * Facet request served by this handler.
  51    */
  52   protected final FacetRequest facetRequest;
  53
  54   /**
  55    * Create a faceted search handler.
  56    * @param taxonomyReader See {@link #getTaxonomyReader()}.
  57    * @param facetRequest See {@link #getFacetRequest()}.
  58    */
  59   public FacetResultsHandler(TaxonomyReader taxonomyReader,
  60                               FacetRequest facetRequest) {
  61     this.taxonomyReader = taxonomyReader;
  62     this.facetRequest = facetRequest;
  63   }
  64
  65   /**
  66    * Fetch results of a single partition, given facet arrays for that partition,
  67    * and based on the matching documents and faceted search parameters.
  68    *
  69    * @param arrays
  70    *          facet arrays for the certain partition
  71    * @param offset
  72    *          offset in input arrays where partition starts
  73    * @return temporary facet result, potentially, to be passed back to
  74    *         <b>this</b> result handler for merging, or <b>null</b> in case that
  75    *         constructor parameter, <code>facetRequest</code>, requests an
  76    *         illegal FacetResult, like, e.g., a root node category path that
  77    *         does not exist in constructor parameter <code>taxonomyReader</code>
  78    *         .
  79    * @throws IOException
  80    *           on error
  81    */
  82   public abstract IntermediateFacetResult fetchPartitionResult(FacetArrays arrays, int offset) throws IOException;
  83
  84   /**
  85    * Merge results of several facet partitions. Logic of the merge is undefined
  86    * and open for interpretations. For example, a merge implementation could
  87    * keep top K results. Passed {@link IntermediateFacetResult} must be ones
  88    * that were created by this handler otherwise a {@link ClassCastException} is
  89    * thrown. In addition, all passed {@link IntermediateFacetResult} must have
  90    * the same {@link FacetRequest} otherwise an {@link IllegalArgumentException}
  91    * is thrown.
  92    *
  93    * @param tmpResults one or more temporary results created by <b>this</b>
  94    *        handler.
  95    * @return temporary facet result that represents to union, as specified by
  96    *         <b>this</b> handler, of the input temporary facet results.
  97    * @throws IOException on error.
  98    * @throws ClassCastException if the temporary result passed was not created
  99    *         by this handler
 100    * @throws IllegalArgumentException if passed <code>facetResults</code> do not
 101    *         have the same {@link FacetRequest}
 102    * @see IntermediateFacetResult#getFacetRequest()
 103    */
 104   public abstract IntermediateFacetResult mergeResults(IntermediateFacetResult... tmpResults)
 105   throws IOException, ClassCastException, IllegalArgumentException;
 106
 107   /**
 108    * Create a facet result from the temporary result.
 109    * @param tmpResult temporary result to be rendered as a {@link FacetResult}
 110    * @throws IOException on error.
 111    */
 112   public abstract FacetResult renderFacetResult(IntermediateFacetResult tmpResult) throws IOException ;
 113
 114   /**
 115    * Perform any rearrangement as required on a facet result that has changed after
 116    * it was rendered.
 117    * <P>
 118    * Possible use case: a sampling facets accumulator invoked another
 119    * other facets accumulator on a sample set of documents, obtained
 120    * rendered facet results, fixed their counts, and now it is needed
 121    * to sort the results differently according to the fixed counts.
 122    * @param facetResult result to be rearranged.
 123    * @see FacetResultNode#setValue(double)
 124    */
 125   public abstract FacetResult rearrangeFacetResult(FacetResult facetResult);
 126
 127   /**
 128    * Label results according to settings in {@link FacetRequest},
 129    * such as {@link FacetRequest#getNumLabel()}.
 130    * Usually invoked by {@link FacetsAccumulator#accumulate(ScoredDocIDs)}
 131    * @param facetResult facet result to be labeled.
 132    * @throws IOException on error
 133    */
 134   public abstract void labelResult (FacetResult facetResult) throws IOException;
 135
 136   /** Return taxonomy reader used for current facets accumulation operation. */
 137   public final TaxonomyReader getTaxonomyReader() {
 138     return this.taxonomyReader;
 139   }
 140
 141   /** Return the facet request served by this handler. */
 142   public final FacetRequest getFacetRequest() {
 143     return this.facetRequest;
 144   }
 145
 146   /**
 147    * Check if an array contains the partition which contains ordinal
 148    *
 149    * @param ordinal
 150    *          checked facet
 151    * @param facetArrays
 152    *          facet arrays for the certain partition
 153    * @param offset
 154    *          offset in input arrays where partition starts
 155    */
 156   protected boolean isSelfPartition (int ordinal, FacetArrays facetArrays, int offset) {
 157     int partitionSize = facetArrays.getArraysLength();
 158     return ordinal / partitionSize == offset / partitionSize;
 159   }
 160
 161 }