## org.apache.lucene.facet.enhancements
Interface CategoryEnhancement

All Known Implementing Classes:
  AssociationEnhancement

    public interface CategoryEnhancement

This interface allows easy addition of enhanced category features. Usually, a `CategoryEnhancement` will correspond to a `CategoryProperty`.

A category enhancement can contribute to the index in two possible ways:

1. To each category with data relevant to the enhancement, add this data to the category's token payload, through `getCategoryTokenBytes(CategoryAttribute)`. This data will be read during search using `extractCategoryTokenData(byte[], int, int)`.
2. To each document which contains categories with data relevant to the enhancement, add a `CategoryListTokenizer` through `getCategoryListTokenizer(TokenStream, EnhancementsIndexingParams, TaxonomyWriter)` . The `CategoryListTokenizer` should add a single token which includes all the enhancement relevant data from the categories. The category list token's text is defined by `getCategoryListTermText()`.

WARNING: This API is experimental and might change in incompatible ways in the next release.

Method Summary
`boolean` `equals(Object o)` Category enhancements must override `Object.equals(Object)`, as it is used in `EnhancementsPayloadIterator.getCategoryData(CategoryEnhancement)`.
`Object` `extractCategoryTokenData(byte[] buffer, int offset, int length)` Get the data of this enhancement from a category token payload.
`boolean` `generatesCategoryList()` Declarative method to indicate whether this enhancement generates separate category list.
`String` `getCategoryListTermText()` Returns the text of this enhancement's category list term.
`CategoryListTokenizer` `getCategoryListTokenizer(TokenStream tokenizer, EnhancementsIndexingParams indexingParams, TaxonomyWriter taxonomyWriter)` Get the `CategoryListTokenizer` which generates the category list for this enhancement.
`byte[]` `getCategoryTokenBytes(CategoryAttribute categoryAttribute)` Get the bytes to be added to the category token payload for this enhancement.
`Class<? extends CategoryProperty>` `getRetainableProperty()` Get a `CategoryProperty` class to be retained when creating `CategoryParentsStream`.

Method Detail

### getCategoryTokenBytes

    byte[] getCategoryTokenBytes(CategoryAttribute categoryAttribute)

  Get the bytes to be added to the category token payload for this enhancement.

  NOTE: The returned array is copied, it is recommended to allocate a new one each time.

  The bytes generated by this method are the input of `extractCategoryTokenData(byte[], int, int)`.

  Parameters:
    `categoryAttribute` - The attribute of the category.
  Returns:
    The bytes to be added to the category token payload for this enhancement.

### extractCategoryTokenData

    Object extractCategoryTokenData(byte[] buffer,
                                    int offset,
                                    int length)

  Get the data of this enhancement from a category token payload.

  The input bytes for this method are generated in `getCategoryTokenBytes(CategoryAttribute)`.

  Parameters:
    `buffer` - The payload buffer.
    `offset` - The offset of this enhancement's data in the buffer.
    `length` - The length of this enhancement's data (bytes).
  Returns:
    An Object containing the data.

### generatesCategoryList

    boolean generatesCategoryList()

  Declarative method to indicate whether this enhancement generates separate category list.

  Returns:
    `true` if generates category list, else `false`.

### getCategoryListTermText

    String getCategoryListTermText()

  Returns the text of this enhancement's category list term.

  Returns:
    The text of this enhancement's category list term.

### getCategoryListTokenizer

    CategoryListTokenizer getCategoryListTokenizer(TokenStream tokenizer,
                                                   EnhancementsIndexingParams indexingParams,
                                                   TaxonomyWriter taxonomyWriter)

  Get the `CategoryListTokenizer` which generates the category list for this enhancement. If `generatesCategoryList()` returns `false` this method will not be called.

  Parameters:
    `tokenizer` - The input stream containing categories.
    `indexingParams` - The indexing params to use.
    `taxonomyWriter` - The taxonomy to add categories and get their ordinals.
  Returns:
    A `CategoryListTokenizer` generating the category list for this enhancement, with `tokenizer` as it's input.

### getRetainableProperty

    Class<? extends CategoryProperty> getRetainableProperty()

  Get a `CategoryProperty` class to be retained when creating `CategoryParentsStream`.

  Returns:
    the `CategoryProperty` class to be retained when creating `CategoryParentsStream`, or `null` if there is no such property.

### equals

    boolean equals(Object o)

  Category enhancements must override `Object.equals(Object)`, as it is used in `EnhancementsPayloadIterator.getCategoryData(CategoryEnhancement)`.

  Overrides:
    `equals` in class `Object`