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:

  • The ordinal is an integer that starts at 0 for the first category (which is always the root category), and grows contiguously as more categories are added; Note that once a category is added, it can never be deleted.
  • The path is a CategoryPath object specifying the category's position in the hierarchy.

Notes about concurrent access to the taxonomy:

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

This is a Lucene.NET EXPERIMENTAL API, use at your own risk
Inheritance
System.Object
TaxonomyReader
DirectoryTaxonomyReader
Namespace: Lucene.Net.Facet.Taxonomy
Assembly: Lucene.Net.Facet.dll
Syntax
public abstract class TaxonomyReader : IDisposable

Constructors

| Improve this Doc View Source

TaxonomyReader()

Sole constructor.

Declaration
public TaxonomyReader()

Fields

| Improve this Doc View Source

INVALID_ORDINAL

Ordinals are always non-negative, so a negative ordinal can be used to signify an error. Methods here return INVALID_ORDINAL (-1) in this case.

Declaration
public const int INVALID_ORDINAL = null
Field Value
Type Description
System.Int32
| Improve this Doc View Source

ROOT_ORDINAL

The root category (the category with the empty path) always has the ordinal 0, to which we give a name ROOT_ORDINAL. GetOrdinal(FacetLabel) of an empty path will always return ROOT_ORDINAL, and GetPath(Int32) with ROOT_ORDINAL will return the empty path.

Declaration
public const int ROOT_ORDINAL = null
Field Value
Type Description
System.Int32

Properties

| Improve this Doc View Source

CommitUserData

Retrieve user committed data.

Declaration
public abstract IDictionary<string, string> CommitUserData { get; }
Property Value
Type Description
IDictionary<System.String, System.String>
See Also
| Improve this Doc View Source

Count

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).

Declaration
public abstract int Count { get; }
Property Value
Type Description
System.Int32
| Improve this Doc View Source

ParallelTaxonomyArrays

Returns a ParallelTaxonomyArrays object which can be used to efficiently traverse the taxonomy tree.

Declaration
public abstract ParallelTaxonomyArrays ParallelTaxonomyArrays { get; }
Property Value
Type Description
ParallelTaxonomyArrays
| Improve this Doc View Source

RefCount

Returns the current refCount for this taxonomy reader.

Declaration
public int RefCount { get; }
Property Value
Type Description
System.Int32

Methods

| Improve this Doc View Source

DecRef()

Expert: decreases the refCount of this TaxonomyReader instance. If the refCount drops to 0 this taxonomy reader is closed.

Declaration
public void DecRef()
| Improve this Doc View Source

Dispose()

Declaration
public void Dispose()
| Improve this Doc View Source

Dispose(Boolean)

Declaration
protected virtual void Dispose(bool disposing)
Parameters
Type Name Description
System.Boolean disposing
| Improve this Doc View Source

DoClose()

performs the actual task of closing the resources that are used by the taxonomy reader.

Declaration
protected abstract void DoClose()
| Improve this Doc View Source

DoOpenIfChanged()

Implements the actual opening of a new TaxonomyReader instance if the taxonomy has changed.

Declaration
protected abstract TaxonomyReader DoOpenIfChanged()
Returns
Type Description
TaxonomyReader
See Also
| Improve this Doc View Source

EnsureOpen()

Throws if this is disposed

Declaration
protected void EnsureOpen()
| Improve this Doc View Source

GetChildren(Int32)

Returns an iterator over the children of the given ordinal.

Declaration
public virtual TaxonomyReader.ChildrenIterator GetChildren(int ordinal)
Parameters
Type Name Description
System.Int32 ordinal
Returns
Type Description
TaxonomyReader.ChildrenIterator
| Improve this Doc View Source

GetOrdinal(FacetLabel)

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).

Declaration
public abstract int GetOrdinal(FacetLabel categoryPath)
Parameters
Type Name Description
FacetLabel categoryPath
Returns
Type Description
System.Int32

the category's ordinal or INVALID_ORDINAL if the category wasn't found.

| Improve this Doc View Source

GetOrdinal(String, String[])

Returns ordinal for the dim + path.

Declaration
public virtual int GetOrdinal(string dim, string[] path)
Parameters
Type Name Description
System.String dim
System.String[] path
Returns
Type Description
System.Int32
| Improve this Doc View Source

GetPath(Int32)

Returns the path name of the category with the given ordinal.

Declaration
public abstract FacetLabel GetPath(int ordinal)
Parameters
Type Name Description
System.Int32 ordinal
Returns
Type Description
FacetLabel
| Improve this Doc View Source

IncRef()

Expert: increments the refCount of this TaxonomyReader instance. RefCounts can be used to determine when a taxonomy reader can be closed safely, i.e. as soon as there are no more references. Be sure to always call a corresponding DecRef(), in a finally clause; otherwise the reader may never be disposed.

Declaration
public void IncRef()
| Improve this Doc View Source

OpenIfChanged<T>(T)

If the taxonomy has changed since the provided reader was opened, open and return a new 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.

Declaration
public static T OpenIfChanged<T>(T oldTaxoReader)
    where T : TaxonomyReader
Parameters
Type Name Description
T oldTaxoReader
Returns
Type Description
T
Type Parameters
Name Description
T
| Improve this Doc View Source

TryIncRef()

Expert: increments the refCount of this TaxonomyReader instance only if it has not been closed yet. Returns true on success.

Declaration
public bool TryIncRef()
Returns
Type Description
System.Boolean