package org.apache.lucene.facet.search.results;
import java.io.IOException;
import org.apache.lucene.facet.search.FacetResultsHandler;
import org.apache.lucene.facet.search.params.FacetRequest;
import org.apache.lucene.facet.search.sampling.SampleFixer;
import org.apache.lucene.facet.taxonomy.CategoryPath;
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.
*/
/**
* Result of faceted search for a certain taxonomy node.
*
* @lucene.experimental
*/
public interface FacetResultNode {
/**
* String representation of this facet result node.
* Use with caution: might return a very long string.
* @param prefix prefix for each result line
*/
public String toString(String prefix);
/**
* Ordinal of the category of this result.
*/
public int getOrdinal();
/**
* Category path of the category of this result, or null if not computed,
* because the application did not request to compute it.
* To force computing the label in case not yet computed use
* {@link #getLabel(TaxonomyReader)}.
* @see FacetRequest#getNumLabel()
* @see #getLabel(TaxonomyReader)
*/
public CategoryPath getLabel();
/**
* Category path of the category of this result.
* If not already computed, will be computed now.
* <p>
* Use with <b>caution</b>: loading a label for results is costly, performance wise.
* Therefore force labels loading only when really needed.
* @param taxonomyReader taxonomy reader for forcing (lazy) labeling of this result.
* @throws IOException on error
* @see FacetRequest#getNumLabel()
*/
public CategoryPath getLabel(TaxonomyReader taxonomyReader) throws IOException;
/**
* Value of this result - usually either count or a value derived from some
* computing on the association of it.
*/
public double getValue();
/**
* Value of screened out sub results.
* <p>
* If only part of valid results are returned, e.g. because top K were requested,
* provide info on "what else is there under this result node".
*/
public double getResidue();
/**
* Contained sub results.
* These are either child facets, if a tree result was requested, or simply descendants, in case
* tree result was not requested. In the first case, all returned are both descendants of
* this node in the taxonomy and siblings of each other in the taxonomy.
* In the latter case they are only guaranteed to be descendants of
* this node in the taxonomy.
*/
public Iterable<? extends FacetResultNode> getSubResults();
/**
* Number of sub results
*/
public int getNumSubResults();
/**
* Expert: Set a new value for this result node.
* <p>
* Allows to modify the value of this facet node.
* Used for example to tune a sampled value, e.g. by
* {@link SampleFixer#fixResult(org.apache.lucene.facet.search.ScoredDocIDs, FacetResult)}
* @param value the new value to set
* @see #getValue()
* @see FacetResultsHandler#rearrangeFacetResult(FacetResult)
*/
public void setValue(double value);
}