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();