|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.apache.lucene.facet.taxonomy.TaxonomyReader
public abstract class TaxonomyReader
TaxonomyReader is the read-only interface with which the faceted-search library uses the taxonomy during search time.
A TaxonomyReader holds a list of categories. Each category has a serial number which we call an "ordinal", and a hierarchical "path" name:
An implementation must allow multiple readers to be active concurrently with a single writer. Readers follow so-called "point in time" semantics, i.e., a TaxonomyReader object will only see taxonomy entries which were available at the time it was created. What the writer writes is only available to (new) readers after the writer's commit() is called.
In faceted search, two separate indices are used: the main Lucene index, and the taxonomy. Because the main index refers to the categories listed in the taxonomy, it is important to open the taxonomy *after* opening the main index, and it is also necessary to reopen() the taxonomy after reopen()ing the main index.
This order is important, otherwise it would be possible for the main index to refer to a category which is not yet visible in the old snapshot of the taxonomy. Note that it is indeed fine for the the taxonomy to be opened after the main index - even a long time after. The reason is that once a category is added to the taxonomy, it can never be changed or deleted, so there is no danger that a "too new" taxonomy not being consistent with an older index.
Field Summary | |
---|---|
static int |
INVALID_ORDINAL
Ordinals are always non-negative, so a negative ordinal can be used to signify an error. |
static int |
ROOT_ORDINAL
The root category (the category with the empty path) always has the ordinal 0, to which we give a name ROOT_ORDINAL. |
Constructor Summary | |
---|---|
TaxonomyReader()
|
Method Summary | ||
---|---|---|
void |
close()
|
|
void |
decRef()
Expert: decreases the refCount of this TaxonomyReader instance. |
|
protected abstract void |
doClose()
performs the actual task of closing the resources that are used by the taxonomy reader. |
|
protected abstract TaxonomyReader |
doOpenIfChanged()
Implements the actual opening of a new TaxonomyReader instance if
the taxonomy has changed. |
|
protected void |
ensureOpen()
|
|
abstract Map<String,String> |
getCommitUserData()
Retrieve user committed data. |
|
abstract int |
getOrdinal(CategoryPath categoryPath)
Returns the ordinal of the category given as a path. |
|
abstract ParallelTaxonomyArrays |
getParallelTaxonomyArrays()
Returns a ParallelTaxonomyArrays object which can be used to
efficiently traverse the taxonomy tree. |
|
abstract 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 ROOT_ORDINAL , an
INVALID_ORDINAL is returned. |
|
abstract CategoryPath |
getPath(int ordinal)
Returns the path name of the category with the given ordinal. |
|
int |
getRefCount()
Returns the current refCount for this taxonomy reader. |
|
abstract int |
getSize()
Returns the number of categories in the taxonomy. |
|
void |
incRef()
Expert: increments the refCount of this TaxonomyReader instance. |
|
static
|
openIfChanged(T oldTaxoReader)
If the taxonomy has changed since the provided reader was opened, open and return a new TaxonomyReader ; else, return null . |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int ROOT_ORDINAL
getOrdinal(CategoryPath)
of an empty path will always return ROOT_ORDINAL
, and
getPath(int)
with ROOT_ORDINAL
will return the empty path.
public static final int INVALID_ORDINAL
Constructor Detail |
---|
public TaxonomyReader()
Method Detail |
---|
public static <T extends TaxonomyReader> T openIfChanged(T oldTaxoReader) throws IOException
TaxonomyReader
; else, return null
. The new
reader, if not null
, will be the same type of reader as the one
given to this method.
This method is typically far less costly than opening a fully new
TaxonomyReader
as it shares resources with the provided
TaxonomyReader
, when possible.
IOException
protected abstract void doClose() throws IOException
IOException
protected abstract TaxonomyReader doOpenIfChanged() throws IOException
TaxonomyReader
instance if
the taxonomy has changed.
IOException
openIfChanged(TaxonomyReader)
protected final void ensureOpen() throws AlreadyClosedException
AlreadyClosedException
- if this IndexReader is closedpublic final void close() throws IOException
close
in interface Closeable
IOException
public final void decRef() throws IOException
IOException
public abstract ParallelTaxonomyArrays getParallelTaxonomyArrays() throws IOException
ParallelTaxonomyArrays
object which can be used to
efficiently traverse the taxonomy tree.
IOException
public abstract Map<String,String> getCommitUserData() throws IOException
IOException
TaxonomyWriter.setCommitData(Map)
public abstract int getOrdinal(CategoryPath categoryPath) throws IOException
INVALID_ORDINAL
if the category
wasn't foun.
IOException
public abstract int getParent(int ordinal) throws IOException
ROOT_ORDINAL
, an
INVALID_ORDINAL
is returned.
ROOT_ORDINAL
is returned.
ArrayIndexOutOfBoundsException
- if an invalid ordinal is given (negative or beyond the last
available ordinal)
IOException
public abstract CategoryPath getPath(int ordinal) throws IOException
IOException
public final int getRefCount()
public abstract int getSize()
public final void incRef()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |