org.apache.lucene.facet.taxonomy.directory

## Class DirectoryTaxonomyReader

- java.lang.Object
- - org.apache.lucene.facet.taxonomy.TaxonomyReader
  - - org.apache.lucene.facet.taxonomy.directory.DirectoryTaxonomyReader

All Implemented Interfaces:
  Closeable, AutoCloseable

    public class DirectoryTaxonomyReader
    extends TaxonomyReader

A `TaxonomyReader` which retrieves stored taxonomy information from a `Directory`.

Reading from the on-disk index on every method call is too slow, so this implementation employs caching: Some methods cache recent requests and their results, while other methods prefetch all the data into memory and then provide answers directly from in-memory tables. See the documentation of individual methods for comments on their performance.

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

### Field Summary

### Fields inherited from class org.apache.lucene.facet.taxonomy.TaxonomyReader

`INVALID_ORDINAL, ROOT_ORDINAL`

### Constructor Summary

Constructors
Constructor and Description
`DirectoryTaxonomyReader(Directory directory)` Open for reading a taxonomy stored in a given `Directory`.
`DirectoryTaxonomyReader(DirectoryTaxonomyWriter taxoWriter)` Opens a `DirectoryTaxonomyReader` over the given `DirectoryTaxonomyWriter` (for NRT).

### Method Summary

Methods
`protected void` `doClose()` performs the actual task of closing the resources that are used by the taxonomy reader.
`protected DirectoryTaxonomyReader` `doOpenIfChanged()` Implements the opening of a new `DirectoryTaxonomyReader` instance if the taxonomy has changed.
`Map<String,String>` `getCommitUserData()` Retrieve user committed data.
`int` `getOrdinal(CategoryPath cp)` Returns the ordinal of the category given as a path.
`ParallelTaxonomyArrays` `getParallelTaxonomyArrays()` Returns a `ParallelTaxonomyArrays` object which can be used to efficiently traverse the taxonomy tree.
`int` `getParent(int ordinal)` Returns the ordinal of the parent category of the category with the given ordinal, according to the following rules: If the given ordinal is the `TaxonomyReader.ROOT_ORDINAL`, an `TaxonomyReader.INVALID_ORDINAL` is returned.
`CategoryPath` `getPath(int ordinal)` Returns the path name of the category with the given ordinal.
`int` `getSize()` Returns the number of categories in the taxonomy.
`protected DirectoryReader` `openIndexReader(Directory directory)`
`protected DirectoryReader` `openIndexReader(IndexWriter writer)`
`void` `setCacheSize(int size)` setCacheSize controls the maximum allowed size of each of the caches used by `getPath(int)` and `getOrdinal(CategoryPath)`.
`void` `setDelimiter(char delimiter)` setDelimiter changes the character that the taxonomy uses in its internal storage as a delimiter between category components.
`String` `toString(int max)`

### Methods inherited from class org.apache.lucene.facet.taxonomy.TaxonomyReader

`close, decRef, ensureOpen, getRefCount, incRef, openIfChanged`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### DirectoryTaxonomyReader

    public DirectoryTaxonomyReader(Directory directory)
                            throws IOException

Open for reading a taxonomy stored in a given `Directory`.

Parameters:
  `directory` - The `Directory` in which the taxonomy resides.
Throws:
  `CorruptIndexException` - if the Taxonomy is corrupt.
  `IOException` - if another error occurred.

#### DirectoryTaxonomyReader

    public DirectoryTaxonomyReader(DirectoryTaxonomyWriter taxoWriter)
                            throws IOException

Opens a `DirectoryTaxonomyReader` over the given `DirectoryTaxonomyWriter` (for NRT).

Parameters:
  `taxoWriter` - The `DirectoryTaxonomyWriter` from which to obtain newly added categories, in real-time.
Throws:
  `IOException`

### Method Detail

#### doClose

    protected void doClose()
                    throws IOException

Description copied from class: `TaxonomyReader`
performs the actual task of closing the resources that are used by the taxonomy reader.

Specified by:
  `doClose` in class `TaxonomyReader`
Throws:
  `IOException`

#### doOpenIfChanged

    protected DirectoryTaxonomyReader doOpenIfChanged()
                                               throws IOException

Implements the opening of a new `DirectoryTaxonomyReader` instance if the taxonomy has changed.

NOTE: the returned `DirectoryTaxonomyReader` shares the ordinal and category caches with this reader. This is not expected to cause any issues, unless the two instances continue to live. The reader guarantees that the two instances cannot affect each other in terms of correctness of the caches, however if the size of the cache is changed through `setCacheSize(int)`, it will affect both reader instances.

Specified by:
  `doOpenIfChanged` in class `TaxonomyReader`
Throws:
  `IOException`
See Also:
  `TaxonomyReader.openIfChanged(TaxonomyReader)`

#### openIndexReader

    protected DirectoryReader openIndexReader(Directory directory)
                                       throws IOException

Throws:
  `IOException`

#### openIndexReader

    protected DirectoryReader openIndexReader(IndexWriter writer)
                                       throws IOException

Throws:
  `IOException`

#### getParallelTaxonomyArrays

    public ParallelTaxonomyArrays getParallelTaxonomyArrays()
                                                     throws IOException

Description copied from class: `TaxonomyReader`
Returns a `ParallelTaxonomyArrays` object which can be used to efficiently traverse the taxonomy tree.

Specified by:
  `getParallelTaxonomyArrays` in class `TaxonomyReader`
Throws:
  `IOException`

#### getCommitUserData

    public Map<String,String> getCommitUserData()
                                         throws IOException

Description copied from class: `TaxonomyReader`
Retrieve user committed data.

Specified by:
  `getCommitUserData` in class `TaxonomyReader`
Throws:
  `IOException`
See Also:
  `TaxonomyWriter.setCommitData(Map)`

#### getOrdinal

    public int getOrdinal(CategoryPath cp)
                   throws IOException

Description copied from class: `TaxonomyReader`
Returns the ordinal of the category given as a path. The ordinal is the category's serial number, an integer which starts with 0 and grows as more categories are added (note that once a category is added, it can never be deleted).

Specified by:
  `getOrdinal` in class `TaxonomyReader`
Returns:
  the category's ordinal or `TaxonomyReader.INVALID_ORDINAL` if the category wasn't foun.
Throws:
  `IOException`

#### getParent

    public int getParent(int ordinal)
                  throws IOException

Description copied from class: `TaxonomyReader`
Returns the ordinal of the parent category of the category with the given ordinal, according to the following rules:

- If the given ordinal is the `TaxonomyReader.ROOT_ORDINAL`, an `TaxonomyReader.INVALID_ORDINAL` is returned.
- If the given ordinal is a top-level category, the `TaxonomyReader.ROOT_ORDINAL` is returned.
- If the given ordinal is an existing category, returns the ordinal of its parent

Specified by:
  `getParent` in class `TaxonomyReader`
Throws:
  `IOException`

#### getPath

    public CategoryPath getPath(int ordinal)
                         throws IOException

Description copied from class: `TaxonomyReader`
Returns the path name of the category with the given ordinal.

Specified by:
  `getPath` in class `TaxonomyReader`
Throws:
  `IOException`

#### getSize

    public int getSize()

Description copied from class: `TaxonomyReader`
Returns the number of categories in the taxonomy. Note that the number of categories returned is often slightly higher than the number of categories inserted into the taxonomy; This is because when a category is added to the taxonomy, its ancestors are also added automatically (including the root, which always get ordinal 0).

Specified by:
  `getSize` in class `TaxonomyReader`

#### setCacheSize

    public void setCacheSize(int size)

setCacheSize controls the maximum allowed size of each of the caches used by `getPath(int)` and `getOrdinal(CategoryPath)`.

Currently, if the given size is smaller than the current size of a cache, it will not shrink, and rather we be limited to its current size.

Parameters:
  `size` - the new maximum cache size, in number of entries.

#### setDelimiter

    public void setDelimiter(char delimiter)

setDelimiter changes the character that the taxonomy uses in its internal storage as a delimiter between category components. Do not use this method unless you really know what you are doing.

If you do use this method, make sure you call it before any other methods that actually queries the taxonomy. Moreover, make sure you always pass the same delimiter for all LuceneTaxonomyWriter and LuceneTaxonomyReader objects you create.

#### toString

    public String toString(int max)