1 package org.apache.lucene.facet.search.results;
3 import java.io.IOException;
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;
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
19 * http://www.apache.org/licenses/LICENSE-2.0
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.
29 * Result of faceted search for a certain taxonomy node.
31 * @lucene.experimental
33 public interface FacetResultNode {
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
40 public String toString(String prefix);
43 * Ordinal of the category of this result.
45 public int getOrdinal();
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)
55 public CategoryPath getLabel();
58 * Category path of the category of this result.
59 * If not already computed, will be computed now.
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()
67 public CategoryPath getLabel(TaxonomyReader taxonomyReader) throws IOException;
70 * Value of this result - usually either count or a value derived from some
71 * computing on the association of it.
73 public double getValue();
76 * Value of screened out sub results.
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".
81 public double getResidue();
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.
91 public Iterable<? extends FacetResultNode> getSubResults();
94 * Number of sub results
96 public int getNumSubResults();
99 * Expert: Set a new value for this result node.
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
106 * @see FacetResultsHandler#rearrangeFacetResult(FacetResult)
108 public void setValue(double value);