org.apache.lucene.facet.taxonomy.directory
Class DirectoryTaxonomyReader

java.lang.Object
  extended by org.apache.lucene.facet.taxonomy.TaxonomyReader
      extended by org.apache.lucene.facet.taxonomy.directory.DirectoryTaxonomyReader
All Implemented Interfaces:
Closeable

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
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
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:

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)


Copyright © 2000-2013 Apache Software Foundation. All Rights Reserved.