lucene-java-3.4.0/lucene/contrib/facet/src/java/org/apache/lucene/facet/search/results/FacetResultNode.java

   1 package org.apache.lucene.facet.search.results;
   2
   3 import java.io.IOException;
   4
   5 import org.apache.lucene.facet.search.FacetResultsHandler;
   6 import org.apache.lucene.facet.search.params.FacetRequest;
   7 import org.apache.lucene.facet.search.sampling.SampleFixer;
   8 import org.apache.lucene.facet.taxonomy.CategoryPath;
   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  * Result of faceted search for a certain taxonomy node.
  30  *
  31  * @lucene.experimental
  32  */
  33 public interface FacetResultNode {
  34
  35   /**
  36    * String representation of this facet result node.
  37    * Use with caution: might return a very long string.
  38    * @param prefix prefix for each result line
  39    */
  40   public String toString(String prefix);
  41
  42   /**
  43    * Ordinal of the category of this result.
  44    */
  45   public int getOrdinal();
  46
  47   /**
  48    * Category path of the category of this result, or null if not computed,
  49    * because the application did not request to compute it.
  50    * To force computing the label in case not yet computed use
  51    * {@link #getLabel(TaxonomyReader)}.
  52    * @see FacetRequest#getNumLabel()
  53    * @see #getLabel(TaxonomyReader)
  54    */
  55   public CategoryPath getLabel();
  56
  57   /**
  58    * Category path of the category of this result.
  59    * If not already computed, will be computed now.
  60    * <p>
  61    * Use with <b>caution</b>: loading a label for results is costly, performance wise.
  62    * Therefore force labels loading only when really needed.
  63    * @param taxonomyReader taxonomy reader for forcing (lazy) labeling of this result.
  64    * @throws IOException on error
  65    * @see FacetRequest#getNumLabel()
  66    */
  67   public CategoryPath getLabel(TaxonomyReader taxonomyReader) throws IOException;
  68
  69   /**
  70    * Value of this result - usually either count or a value derived from some
  71    * computing on the association of it.
  72    */
  73   public double getValue();
  74
  75   /**
  76    * Value of screened out sub results.
  77    * <p>
  78    * If only part of valid results are returned, e.g. because top K were requested,
  79    * provide info on "what else is there under this result node".
  80    */
  81   public double getResidue();
  82
  83   /**
  84    * Contained sub results.
  85    * These are either child facets, if a tree result was requested, or simply descendants, in case
  86    * tree result was not requested. In the first case, all returned are both descendants of
  87    * this node in the taxonomy and siblings of each other in the taxonomy.
  88    * In the latter case they are only guaranteed to be descendants of
  89    * this node in the taxonomy.
  90    */
  91   public Iterable<? extends FacetResultNode> getSubResults();
  92
  93   /**
  94    * Number of sub results
  95    */
  96   public int getNumSubResults();
  97
  98   /**
  99    * Expert: Set a new value for this result node.
 100    * <p>
 101    * Allows to modify the value of this facet node.
 102    * Used for example to tune a sampled value, e.g. by
 103    * {@link SampleFixer#fixResult(org.apache.lucene.facet.search.ScoredDocIDs, FacetResult)}
 104    * @param value the new value to set
 105    * @see #getValue()
 106    * @see FacetResultsHandler#rearrangeFacetResult(FacetResult)
 107    */
 108   public void setValue(double value);
 109
 110 }