lucene-java-3.4.0/lucene/contrib/facet/src/java/org/apache/lucene/facet/enhancements/CategoryEnhancement.java

   1 package org.apache.lucene.facet.enhancements;
   2
   3 import org.apache.lucene.analysis.TokenStream;
   4
   5 import org.apache.lucene.facet.enhancements.params.EnhancementsIndexingParams;
   6 import org.apache.lucene.facet.index.attributes.CategoryAttribute;
   7 import org.apache.lucene.facet.index.attributes.CategoryProperty;
   8 import org.apache.lucene.facet.index.streaming.CategoryListTokenizer;
   9 import org.apache.lucene.facet.index.streaming.CategoryParentsStream;
  10 import org.apache.lucene.facet.taxonomy.TaxonomyWriter;
  11
  12 /**
  13  * Licensed to the Apache Software Foundation (ASF) under one or more
  14  * contributor license agreements.  See the NOTICE file distributed with
  15  * this work for additional information regarding copyright ownership.
  16  * The ASF licenses this file to You under the Apache License, Version 2.0
  17  * (the "License"); you may not use this file except in compliance with
  18  * the License.  You may obtain a copy of the License at
  19  *
  20  *     http://www.apache.org/licenses/LICENSE-2.0
  21  *
  22  * Unless required by applicable law or agreed to in writing, software
  23  * distributed under the License is distributed on an "AS IS" BASIS,
  24  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  25  * See the License for the specific language governing permissions and
  26  * limitations under the License.
  27  */
  28
  29 /**
  30  * This interface allows easy addition of enhanced category features. Usually, a
  31  * {@link CategoryEnhancement} will correspond to a {@link CategoryProperty}.
  32  * <p>
  33  * A category enhancement can contribute to the index in two possible ways:
  34  * <ol>
  35  * <li>To each category with data relevant to the enhancement, add this data to
  36  * the category's token payload, through
  37  * {@link #getCategoryTokenBytes(CategoryAttribute)}. This data will be read
  38  * during search using {@link #extractCategoryTokenData(byte[], int, int)}.</li>
  39  * <li>To each document which contains categories with data relevant to the
  40  * enhancement, add a {@link CategoryListTokenizer} through
  41  * {@link #getCategoryListTokenizer(TokenStream, EnhancementsIndexingParams, TaxonomyWriter)}
  42  * . The {@link CategoryListTokenizer} should add a single token which includes
  43  * all the enhancement relevant data from the categories. The category list
  44  * token's text is defined by {@link #getCategoryListTermText()}.</li>
  45  * </ol>
  46  *
  47  * @lucene.experimental
  48  */
  49 public interface CategoryEnhancement {
  50
  51   /**
  52    * Get the bytes to be added to the category token payload for this
  53    * enhancement.
  54    * <p>
  55    * <b>NOTE</b>: The returned array is copied, it is recommended to allocate
  56    * a new one each time.
  57    * <p>
  58    * The bytes generated by this method are the input of
  59    * {@link #extractCategoryTokenData(byte[], int, int)}.
  60    *
  61    * @param categoryAttribute
  62    *            The attribute of the category.
  63    * @return The bytes to be added to the category token payload for this
  64    *         enhancement.
  65    */
  66   byte[] getCategoryTokenBytes(CategoryAttribute categoryAttribute);
  67
  68   /**
  69    * Get the data of this enhancement from a category token payload.
  70    * <p>
  71    * The input bytes for this method are generated in
  72    * {@link #getCategoryTokenBytes(CategoryAttribute)}.
  73    *
  74    * @param buffer
  75    *            The payload buffer.
  76    * @param offset
  77    *            The offset of this enhancement's data in the buffer.
  78    * @param length
  79    *            The length of this enhancement's data (bytes).
  80    * @return An Object containing the data.
  81    */
  82   Object extractCategoryTokenData(byte[] buffer, int offset, int length);
  83
  84   /**
  85    * Declarative method to indicate whether this enhancement generates
  86    * separate category list.
  87    *
  88    * @return {@code true} if generates category list, else {@code false}.
  89    */
  90   boolean generatesCategoryList();
  91
  92   /**
  93    * Returns the text of this enhancement's category list term.
  94    *
  95    * @return The text of this enhancement's category list term.
  96    */
  97   String getCategoryListTermText();
  98
  99   /**
 100    * Get the {@link CategoryListTokenizer} which generates the category list
 101    * for this enhancement. If {@link #generatesCategoryList()} returns
 102    * {@code false} this method will not be called.
 103    *
 104    * @param tokenizer
 105    *            The input stream containing categories.
 106    * @param indexingParams
 107    *            The indexing params to use.
 108    * @param taxonomyWriter
 109    *            The taxonomy to add categories and get their ordinals.
 110    * @return A {@link CategoryListTokenizer} generating the category list for
 111    *         this enhancement, with {@code tokenizer} as it's input.
 112    */
 113   CategoryListTokenizer getCategoryListTokenizer(TokenStream tokenizer,
 114       EnhancementsIndexingParams indexingParams,
 115       TaxonomyWriter taxonomyWriter);
 116
 117   /**
 118    * Get a {@link CategoryProperty} class to be retained when creating
 119    * {@link CategoryParentsStream}.
 120    *
 121    * @return the {@link CategoryProperty} class to be retained when creating
 122    *         {@link CategoryParentsStream}, or {@code null} if there is no
 123    *         such property.
 124    */
 125   Class<? extends CategoryProperty> getRetainableProperty();
 126
 127 }