1 package org.apache.lucene.facet.index.params;
3 import java.io.IOException;
4 import java.io.Serializable;
6 import org.apache.lucene.index.IndexReader;
7 import org.apache.lucene.index.Term;
9 import org.apache.lucene.facet.search.CategoryListIterator;
10 import org.apache.lucene.facet.search.PayloadIntDecodingIterator;
11 import org.apache.lucene.facet.search.TotalFacetCounts;
12 import org.apache.lucene.facet.util.PartitionsUtils;
13 import org.apache.lucene.util.encoding.DGapIntEncoder;
14 import org.apache.lucene.util.encoding.IntDecoder;
15 import org.apache.lucene.util.encoding.IntEncoder;
16 import org.apache.lucene.util.encoding.SortingIntEncoder;
17 import org.apache.lucene.util.encoding.UniqueValuesIntEncoder;
18 import org.apache.lucene.util.encoding.VInt8IntEncoder;
21 * Licensed to the Apache Software Foundation (ASF) under one or more
22 * contributor license agreements. See the NOTICE file distributed with
23 * this work for additional information regarding copyright ownership.
24 * The ASF licenses this file to You under the Apache License, Version 2.0
25 * (the "License"); you may not use this file except in compliance with
26 * the License. You may obtain a copy of the License at
28 * http://www.apache.org/licenses/LICENSE-2.0
30 * Unless required by applicable law or agreed to in writing, software
31 * distributed under the License is distributed on an "AS IS" BASIS,
32 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
33 * See the License for the specific language governing permissions and
34 * limitations under the License.
38 * Contains parameters for a category list *
40 * @lucene.experimental
42 public class CategoryListParams implements Serializable {
44 /** The default term used to store the facets information. */
45 public static final Term DEFAULT_TERM = new Term("$facets", "$fulltree$");
47 private final Term term;
49 private final int hashCode;
52 * Constructs a default category list parameters object, using
53 * {@link #DEFAULT_TERM}.
55 public CategoryListParams() {
60 * Constructs a category list parameters object, using the given {@link Term}.
61 * @param term who's payload hold the category-list.
63 public CategoryListParams(Term term) {
65 // Pre-compute the hashCode because these objects are immutable. Saves
66 // some time on the comparisons later.
67 this.hashCode = term.hashCode();
71 * A {@link Term} who's payload holds the category-list.
73 public final Term getTerm() {
78 * Allows to override how categories are encoded and decoded. A matching
79 * {@link IntDecoder} is provided by the {@link IntEncoder}.
81 * Default implementation creates a new Sorting(<b>Unique</b>(DGap)) encoder.
82 * Uniqueness in this regard means when the same category appears twice in a
83 * document, only one appearance would be encoded. This has effect on facet
86 * Some possible considerations when overriding may be:
88 * <li>an application "knows" that all categories are unique. So no need to
89 * pass through the unique filter.</li>
90 * <li>Another application might wish to count multiple occurrences of the
91 * same category, or, use a faster encoding which will consume more space.</li>
93 * In any event when changing this value make sure you know what you are
94 * doing, and test the results - e.g. counts, if the application is about
97 public IntEncoder createEncoder() {
98 return new SortingIntEncoder(new UniqueValuesIntEncoder(new DGapIntEncoder(new VInt8IntEncoder())));
102 * Equality is defined by the 'term' that defines this category list.
103 * Sub-classes should override this method if a more complex calculation
104 * is needed to ensure equality.
107 public boolean equals(Object o) {
111 if (!(o instanceof CategoryListParams)) {
114 CategoryListParams other = (CategoryListParams) o;
115 if (this.hashCode != other.hashCode) {
118 // The above hashcodes might equal each other in the case of a collision,
119 // so at this point only directly term equality testing will settle
120 // the equality test.
121 return this.term.equals(other.term);
125 * Hashcode is similar to {@link #equals(Object)}, in that it uses
126 * the term that defines this category list to derive the hashcode.
127 * Subclasses need to ensure that equality/hashcode is correctly defined,
128 * or there could be side-effects in the {@link TotalFacetCounts} caching
129 * mechanism (as the filename for a Total Facet Counts array cache
130 * is dependent on the hashCode, so it should consistently return the same
131 * hash for identity).
134 public int hashCode() {
135 return this.hashCode;
139 * Create the category list iterator for the specified partition.
141 public CategoryListIterator createCategoryListIterator(IndexReader reader,
142 int partition) throws IOException {
143 String categoryListTermStr = PartitionsUtils.partitionName(this, partition);
144 Term payloadTerm = term.createTerm(categoryListTermStr);
145 return new PayloadIntDecodingIterator(reader, payloadTerm,
146 createEncoder().createMatchingDecoder());