1 package org.apache.lucene.facet.enhancements;
3 import org.apache.lucene.analysis.TokenStream;
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;
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
20 * http://www.apache.org/licenses/LICENSE-2.0
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.
30 * This interface allows easy addition of enhanced category features. Usually, a
31 * {@link CategoryEnhancement} will correspond to a {@link CategoryProperty}.
33 * A category enhancement can contribute to the index in two possible ways:
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>
47 * @lucene.experimental
49 public interface CategoryEnhancement {
52 * Get the bytes to be added to the category token payload for this
55 * <b>NOTE</b>: The returned array is copied, it is recommended to allocate
56 * a new one each time.
58 * The bytes generated by this method are the input of
59 * {@link #extractCategoryTokenData(byte[], int, int)}.
61 * @param categoryAttribute
62 * The attribute of the category.
63 * @return The bytes to be added to the category token payload for this
66 byte[] getCategoryTokenBytes(CategoryAttribute categoryAttribute);
69 * Get the data of this enhancement from a category token payload.
71 * The input bytes for this method are generated in
72 * {@link #getCategoryTokenBytes(CategoryAttribute)}.
77 * The offset of this enhancement's data in the buffer.
79 * The length of this enhancement's data (bytes).
80 * @return An Object containing the data.
82 Object extractCategoryTokenData(byte[] buffer, int offset, int length);
85 * Declarative method to indicate whether this enhancement generates
86 * separate category list.
88 * @return {@code true} if generates category list, else {@code false}.
90 boolean generatesCategoryList();
93 * Returns the text of this enhancement's category list term.
95 * @return The text of this enhancement's category list term.
97 String getCategoryListTermText();
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.
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.
113 CategoryListTokenizer getCategoryListTokenizer(TokenStream tokenizer,
114 EnhancementsIndexingParams indexingParams,
115 TaxonomyWriter taxonomyWriter);
118 * Get a {@link CategoryProperty} class to be retained when creating
119 * {@link CategoryParentsStream}.
121 * @return the {@link CategoryProperty} class to be retained when creating
122 * {@link CategoryParentsStream}, or {@code null} if there is no
125 Class<? extends CategoryProperty> getRetainableProperty();