+++ /dev/null
-package org.apache.lucene.facet.search.params;
-
-import java.io.IOException;
-
-import org.apache.lucene.index.IndexReader;
-
-import org.apache.lucene.facet.index.params.CategoryListParams;
-import org.apache.lucene.facet.search.CategoryListIterator;
-import org.apache.lucene.facet.search.FacetArrays;
-import org.apache.lucene.facet.search.FacetResultsHandler;
-import org.apache.lucene.facet.search.TopKFacetResultsHandler;
-import org.apache.lucene.facet.search.TopKInEachNodeHandler;
-import org.apache.lucene.facet.search.aggregator.Aggregator;
-import org.apache.lucene.facet.search.cache.CategoryListData;
-import org.apache.lucene.facet.search.cache.CategoryListCache;
-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.
- */
-
-/**
- * Request to accumulate facet information for a specified facet and possibly
- * also some of its descendants, upto a specified depth.
- * <p>
- * The facet request additionally defines what information should
- * be computed within the facet results, if and how should results
- * be ordered, etc.
- * <P>
- * An example facet request is to look at all sub-categories of "Author", and
- * return the 10 with the highest counts (sorted by decreasing count).
- *
- * @lucene.experimental
- */
-public abstract class FacetRequest implements Cloneable {
-
- /**
- * Default depth for facets accumulation.
- * @see #getDepth()
- */
- public static final int DEFAULT_DEPTH = 1;
-
- /**
- * Default sort mode.
- * @see #getSortBy()
- */
- public static final SortBy DEFAULT_SORT_BY = SortBy.VALUE;
-
- /**
- * Default result mode
- * @see #getResultMode()
- */
- public static final ResultMode DEFAULT_RESULT_MODE = ResultMode.GLOBAL_FLAT;
-
- private final CategoryPath categoryPath;
- private final int numResults;
- private int numLabel;
- private int depth;
- private SortOrder sortOrder;
- private SortBy sortBy;
-
- /**
- * Computed at construction, this hashCode is based on two final members
- * {@link CategoryPath} and <code>numResults</code>
- */
- private final int hashCode;
-
- private ResultMode resultMode = DEFAULT_RESULT_MODE;
-
- /**
- * Initialize the request with a given path, and a requested number of facets
- * results. By default, all returned results would be labeled - to alter this
- * default see {@link #setNumLabel(int)}.
- * <p>
- * <b>NOTE:</b> if <code>numResults</code> is given as
- * <code>Integer.MAX_VALUE</code> than all the facet results would be
- * returned, without any limit.
- * <p>
- * <b>NOTE:</b> it is assumed that the given {@link CategoryPath} is not
- * modified after construction of this object. Otherwise, some things may not
- * function properly, e.g. {@link #hashCode()}.
- *
- * @throws IllegalArgumentException if numResults is ≤ 0
- */
- public FacetRequest(CategoryPath path, int numResults) {
- if (numResults <= 0) {
- throw new IllegalArgumentException("num results must be a positive (>0) number: " + numResults);
- }
- if (path == null) {
- throw new IllegalArgumentException("category path cannot be null!");
- }
- categoryPath = path;
- this.numResults = numResults;
- numLabel = numResults;
- depth = DEFAULT_DEPTH;
- sortBy = DEFAULT_SORT_BY;
- sortOrder = SortOrder.DESCENDING;
-
- hashCode = categoryPath.hashCode() ^ this.numResults;
- }
-
- @Override
- public Object clone() throws CloneNotSupportedException {
- // Overridden to make it public
- return super.clone();
- }
-
- public void setNumLabel(int numLabel) {
- this.numLabel = numLabel;
- }
-
- public void setDepth(int depth) {
- this.depth = depth;
- }
-
- public void setSortOrder(SortOrder sortOrder) {
- this.sortOrder = sortOrder;
- }
-
- public void setSortBy(SortBy sortBy) {
- this.sortBy = sortBy;
- }
-
- /**
- * The root category of this facet request. The categories that are returned
- * as a result of this request will all be descendants of this root.
- * <p>
- * <b>NOTE:</b> you should not modify the returned {@link CategoryPath}, or
- * otherwise some methonds may not work properly, e.g. {@link #hashCode()}.
- */
- public final CategoryPath getCategoryPath() {
- return categoryPath;
- }
-
- /**
- * How deeply to look under the given category. If the depth is 0,
- * only the category itself is counted. If the depth is 1, its immediate
- * children are also counted, and so on. If the depth is Integer.MAX_VALUE,
- * all the category's descendants are counted.<br>
- * TODO (Facet): add AUTO_EXPAND option
- */
- public final int getDepth() {
- return depth;
- }
-
- /**
- * If getNumLabel()<getNumResults(), only the first getNumLabel() results
- * will have their category paths calculated, and the rest will only be
- * available as ordinals (category numbers) and will have null paths.
- * <P>
- * If Integer.MAX_VALUE is specified, all
- * results are labled.
- * <P>
- * The purpose of this parameter is to avoid having to run the whole
- * faceted search again when the user asks for more values for the facet;
- * The application can ask (getNumResults()) for more values than it needs
- * to show, but keep getNumLabel() only the number it wants to immediately
- * show. The slow-down caused by finding more values is negligible, because
- * the slowest part - finding the categories' paths, is avoided.
- * <p>
- * Depending on the {@link #getResultMode() LimitsMode},
- * this limit is applied globally or per results node.
- * In the global mode, if this limit is 3,
- * only 3 top results would be labeled.
- * In the per-node mode, if this limit is 3,
- * 3 top children of {@link #getCategoryPath() the target category} would be labeled,
- * as well as 3 top children of each of them, and so forth, until the depth defined
- * by {@link #getDepth()}.
- * @see #getResultMode()
- */
- public final int getNumLabel() {
- return numLabel;
- }
-
- /**
- * The number of sub-categories to return (at most).
- * If the sub-categories are returned.
- * <p>
- * If Integer.MAX_VALUE is specified, all
- * sub-categories are returned.
- * <p>
- * Depending on the {@link #getResultMode() LimitsMode},
- * this limit is applied globally or per results node.
- * In the global mode, if this limit is 3,
- * only 3 top results would be computed.
- * In the per-node mode, if this limit is 3,
- * 3 top children of {@link #getCategoryPath() the target category} would be returned,
- * as well as 3 top children of each of them, and so forth, until the depth defined
- * by {@link #getDepth()}.
- * @see #getResultMode()
- */
- public final int getNumResults() {
- return numResults;
- }
-
- /**
- * Sort options for facet results.
- */
- public enum SortBy {
- /** sort by category ordinal with the taxonomy */
- ORDINAL,
-
- /** sort by computed category value */
- VALUE
- }
-
- /** Specify how should results be sorted. */
- public final SortBy getSortBy() {
- return sortBy;
- }
-
- /** Requested sort order for the results. */
- public enum SortOrder { ASCENDING, DESCENDING }
-
- /** Return the requested order of results. */
- public final SortOrder getSortOrder() {
- return sortOrder;
- }
-
- @Override
- public String toString() {
- return categoryPath.toString()+" nRes="+numResults+" nLbl="+numLabel;
- }
-
- /**
- * Creates a new {@link FacetResultsHandler} that matches the request logic
- * and current settings, such as {@link #getDepth() depth},
- * {@link #getResultMode() limits-mode}, etc, as well as the passed in
- * {@link TaxonomyReader}.
- *
- * @param taxonomyReader taxonomy reader is needed e.g. for knowing the
- * taxonomy size.
- */
- public FacetResultsHandler createFacetResultsHandler(TaxonomyReader taxonomyReader) {
- try {
- if (resultMode == ResultMode.PER_NODE_IN_TREE) {
- return new TopKInEachNodeHandler(taxonomyReader, (FacetRequest) clone());
- }
- return new TopKFacetResultsHandler(taxonomyReader, (FacetRequest) clone());
- } catch (CloneNotSupportedException e) {
- // Shouldn't happen since we implement Cloneable. If it does happen, it is
- // probably because the class was changed to not implement Cloneable
- // anymore.
- throw new RuntimeException(e);
- }
- }
-
- /**
- * Result structure manner of applying request's limits such as
- * {@link #getNumLabel()} and
- * {@link #getNumResults()}.
- */
- public enum ResultMode {
- /** Limits are applied per node, and the result has a full tree structure. */
- PER_NODE_IN_TREE,
-
- /** Limits are applied globally, on total number of results, and the result has a flat structure. */
- GLOBAL_FLAT
- }
-
- /** Return the requested result mode. */
- public final ResultMode getResultMode() {
- return resultMode;
- }
-
- /**
- * @param resultMode the resultMode to set
- * @see #getResultMode()
- */
- public void setResultMode(ResultMode resultMode) {
- this.resultMode = resultMode;
- }
-
- @Override
- public int hashCode() {
- return hashCode;
- }
-
- @Override
- public boolean equals(Object o) {
- if (o instanceof FacetRequest) {
- FacetRequest that = (FacetRequest)o;
- return that.hashCode == this.hashCode &&
- that.categoryPath.equals(this.categoryPath) &&
- that.numResults == this.numResults &&
- that.depth == this.depth &&
- that.resultMode == this.resultMode &&
- that.numLabel == this.numLabel;
- }
- return false;
- }
-
- /**
- * Create an aggregator for this facet request. Aggregator action depends on
- * request definition. For a count request, it will usually increment the
- * count for that facet.
- *
- * @param useComplements
- * whether the complements optimization is being used for current
- * computation.
- * @param arrays
- * provider for facet arrays in use for current computation.
- * @param indexReader
- * index reader in effect.
- * @param taxonomy
- * reader of taxonomy in effect.
- * @throws IOException
- */
- public abstract Aggregator createAggregator(boolean useComplements,
- FacetArrays arrays, IndexReader indexReader,
- TaxonomyReader taxonomy) throws IOException;
-
- /**
- * Create the category list iterator for the specified partition.
- * If a non null cache is provided which contains the required data,
- * use it for the iteration.
- */
- public CategoryListIterator createCategoryListIterator(IndexReader reader,
- TaxonomyReader taxo, FacetSearchParams sParams, int partition)
- throws IOException {
- CategoryListCache clCache = sParams.getClCache();
- CategoryListParams clParams = sParams.getFacetIndexingParams().getCategoryListParams(categoryPath);
- if (clCache!=null) {
- CategoryListData clData = clCache.get(clParams);
- if (clData!=null) {
- return clData.iterator(partition);
- }
- }
- return clParams.createCategoryListIterator(reader, partition);
- }
-
- /**
- * Return the value of a category used for facets computations for this
- * request. For a count request this would be the count for that facet, i.e.
- * an integer number. but for other requests this can be the result of a more
- * complex operation, and the result can be any double precision number.
- * Having this method with a general name <b>value</b> which is double
- * precision allows to have more compact API and code for handling counts and
- * perhaps other requests (such as for associations) very similarly, and by
- * the same code and API, avoiding code duplication.
- *
- * @param arrays
- * provider for facet arrays in use for current computation.
- * @param idx
- * an index into the count arrays now in effect in
- * <code>arrays</code>. E.g., for ordinal number <i>n</i>, with
- * partition, of size <i>partitionSize</i>, now covering <i>n</i>,
- * <code>getValueOf</code> would be invoked with <code>idx</code>
- * being <i>n</i> % <i>partitionSize</i>.
- */
- public abstract double getValueOf(FacetArrays arrays, int idx);
-
- /**
- * Indicates whether this facet request is eligible for applying the complements optimization.
- */
- public boolean supportsComplements() {
- return false; // by default: no
- }
-
- /** Indicates whether the results of this request depends on each result document's score */
- public abstract boolean requireDocumentScore();
-
-}
fnp / pylucene.git / blobdiff