lucene-java-3.4.0/lucene/contrib/facet/src/java/org/apache/lucene/facet/index/params/CategoryListParams.java

   1 package org.apache.lucene.facet.index.params;
   2
   3 import java.io.IOException;
   4 import java.io.Serializable;
   5
   6 import org.apache.lucene.index.IndexReader;
   7 import org.apache.lucene.index.Term;
   8
   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;
  19
  20 /**
  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
  27  *
  28  *     http://www.apache.org/licenses/LICENSE-2.0
  29  *
  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.
  35  */
  36
  37 /**
  38  * Contains parameters for a category list *
  39  *
  40  * @lucene.experimental
  41  */
  42 public class CategoryListParams implements Serializable {
  43
  44   /** The default term used to store the facets information. */
  45   public static final Term DEFAULT_TERM = new Term("$facets", "$fulltree$");
  46
  47   private final Term term;
  48
  49   private final int hashCode;
  50
  51   /**
  52    * Constructs a default category list parameters object, using
  53    * {@link #DEFAULT_TERM}.
  54    */
  55   public CategoryListParams() {
  56     this(DEFAULT_TERM);
  57   }
  58
  59   /**
  60    * Constructs a category list parameters object, using the given {@link Term}.
  61    * @param term who's payload hold the category-list.
  62    */
  63   public CategoryListParams(Term term) {
  64     this.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();
  68   }
  69
  70   /**
  71    * A {@link Term} who's payload holds the category-list.
  72    */
  73   public final Term getTerm() {
  74     return term;
  75   }
  76
  77   /**
  78    * Allows to override how categories are encoded and decoded. A matching
  79    * {@link IntDecoder} is provided by the {@link IntEncoder}.
  80    * <p>
  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
  84    * counting results.
  85    * <p>
  86    * Some possible considerations when overriding may be:
  87    * <ul>
  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>
  92    * </ul>
  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
  95    * counting facets.
  96    */
  97   public IntEncoder createEncoder() {
  98     return new SortingIntEncoder(new UniqueValuesIntEncoder(new DGapIntEncoder(new VInt8IntEncoder())));
  99   }
 100
 101   /**
 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.
 105    */
 106   @Override
 107   public boolean equals(Object o) {
 108     if (o == this) {
 109       return true;
 110     }
 111     if (!(o instanceof CategoryListParams)) {
 112       return false;
 113     }
 114     CategoryListParams other = (CategoryListParams) o;
 115     if (this.hashCode != other.hashCode) {
 116       return false;
 117     }
 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);
 122   }
 123
 124   /**
 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).
 132    */
 133   @Override
 134   public int hashCode() {
 135     return this.hashCode;
 136   }
 137
 138   /**
 139    * Create the category list iterator for the specified partition.
 140    */
 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());
 147   }
 148
 149 }