Class DirectoryTaxonomyWriter

ITaxonomyWriter which uses a to store the taxonomy information on disk, and keeps an additional in-memory cache of some or all categories.

In addition to the permanently-stored information in the , efficiency dictates that we also keep an in-memory cache of recently seen or all categories, so that we do not need to go back to disk for every category addition to see which ordinal this category already has, if any. A ITaxonomyWriterCache object determines the specific caching algorithm used.

This class offers some hooks for extending classes to control the instance that is used. See OpenIndexWriter(Store.Directory, Index.IndexWriterConfig).

@lucene.experimental

Inheritance

System.Object

DirectoryTaxonomyWriter

Implements

ITaxonomyWriter

IDisposable

Index.ITwoPhaseCommit

Namespace: Lucene.Net.Facet.Taxonomy.Directory

Assembly: Lucene.Net.Facet.dll

Syntax

public class DirectoryTaxonomyWriter : object, ITaxonomyWriter, IDisposable, Index.ITwoPhaseCommit

Constructors

DirectoryTaxonomyWriter(Store.Directory, Index.OpenMode)

Creates a new instance with a default cache as defined by DefaultTaxonomyWriterCache().

Declaration

public DirectoryTaxonomyWriter(Store.Directory directory, Index.OpenMode openMode = null)

Parameters

Type	Name	Description
Store.Directory	directory
Index.OpenMode	openMode

DirectoryTaxonomyWriter(Store.Directory, Index.OpenMode, ITaxonomyWriterCache)

Construct a Taxonomy writer.

Declaration

public DirectoryTaxonomyWriter(Store.Directory directory, Index.OpenMode openMode, ITaxonomyWriterCache cache)

Parameters

Type	Name	Description
Store.Directory	directory	The in which to store the taxonomy. Note that the taxonomy is written directly to that directory (not to a subdirectory of it).
Index.OpenMode	openMode	Specifies how to open a taxonomy for writing: means open an existing index for append (failing if the index does not yet exist). means create a new index (first deleting the old one if it already existed). appends to an existing index if there is one, otherwise it creates a new index.
ITaxonomyWriterCache	cache	A ITaxonomyWriterCache implementation which determines the in-memory caching policy. See for example LruTaxonomyWriterCache and Cl2oTaxonomyWriterCache. If null or missing, DefaultTaxonomyWriterCache() is used.

Fields

INDEX_EPOCH

Property name of user commit data that contains the index epoch. The epoch changes whenever the taxonomy is recreated (i.e. opened with .

Applications should not use this property in their commit data because it will be overridden by this taxonomy writer.

Declaration

public const string INDEX_EPOCH = null

Field Value

Type	Description
System.String

Properties

CommitData

Declaration

public virtual IDictionary<string, string> CommitData { get; }

Property Value

Type	Description
IDictionary<System.String, System.String>

Count

Declaration

public virtual int Count { get; }

Property Value

Type	Description
System.Int32

Directory

Returns the of this taxonomy writer.

Declaration

public virtual Store.Directory Directory { get; }

Property Value

Type	Description
Store.Directory

TaxonomyEpoch

Expert: returns current index epoch, if this is a near-real-time reader. Used by DirectoryTaxonomyReader to support NRT.

@lucene.internal

Declaration

public long TaxonomyEpoch { get; }

Property Value

Type	Description
System.Int64

Methods

AddCategory(FacetLabel)

Declaration

public virtual int AddCategory(FacetLabel categoryPath)

Parameters

Type	Name	Description
FacetLabel	categoryPath

Returns

Type	Description
System.Int32

AddTaxonomy(Store.Directory, DirectoryTaxonomyWriter.IOrdinalMap)

Takes the categories from the given taxonomy directory, and adds the missing ones to this taxonomy. Additionally, it fills the given DirectoryTaxonomyWriter.IOrdinalMap with a mapping from the original ordinal to the new ordinal.

Declaration

public virtual void AddTaxonomy(Store.Directory taxoDir, DirectoryTaxonomyWriter.IOrdinalMap map)

Parameters

Type	Name	Description
Store.Directory	taxoDir
DirectoryTaxonomyWriter.IOrdinalMap	map

CloseResources()

A hook for extending classes to close additional resources that were used. The default implementation closes the as well as the ITaxonomyWriterCache instances that were used.

NOTE: if you override this method, you should include a base.CloseResources() call in your implementation.

Declaration

protected virtual void CloseResources()

Commit()

Declaration

public virtual void Commit()

CreateIndexWriterConfig(Index.OpenMode)

Create the that would be used for opening the internal index writer.

Extensions can configure the as they see fit, including setting a , or , different RAM size etc.

NOTE: internal docids of the configured index must not be altered. For that, categories are never deleted from the taxonomy index. In addition, merge policy in effect must not merge none adjacent segments.

Declaration

protected virtual Index.IndexWriterConfig CreateIndexWriterConfig(Index.OpenMode openMode)

Parameters

Type	Name	Description
Index.OpenMode	openMode	see

Returns

Type	Description
Index.IndexWriterConfig

See Also

OpenIndexWriter(Store.Directory, Index.IndexWriterConfig)

DefaultTaxonomyWriterCache()

Defines the default ITaxonomyWriterCache to use in constructors which do not specify one.

The current default is Cl2oTaxonomyWriterCache constructed with the parameters (1024, 0.15f, 3), i.e., the entire taxonomy is cached in memory while building it.

Declaration

public static ITaxonomyWriterCache DefaultTaxonomyWriterCache()

Returns

Type	Description
ITaxonomyWriterCache

Dispose()

Frees used resources as well as closes the underlying , which commits whatever changes made to it to the underlying .

Declaration

public void Dispose()

EnsureOpen()

Verifies that this instance wasn't closed, or throws if it is.

Declaration

protected void EnsureOpen()

FindCategory(FacetLabel)

Look up the given category in the cache and/or the on-disk storage, returning the category's ordinal, or a negative number in case the category does not yet exist in the taxonomy.

Declaration

protected virtual int FindCategory(FacetLabel categoryPath)

Parameters

Type	Name	Description
FacetLabel	categoryPath

Returns

Type	Description
System.Int32

GetParent(Int32)

Declaration

public virtual int GetParent(int ordinal)

Parameters

Type	Name	Description
System.Int32	ordinal

Returns

Type	Description
System.Int32

OpenIndexWriter(Store.Directory, Index.IndexWriterConfig)

Open internal index writer, which contains the taxonomy data.

Extensions may provide their own implementation or instance.

NOTE: the instance this method returns will be disposed upon calling to Dispose().

NOTE: the merge policy in effect must not merge none adjacent segments. See comment in CreateIndexWriterConfig(Index.OpenMode) for the logic behind this.

Declaration

protected virtual Index.IndexWriter OpenIndexWriter(Store.Directory directory, Index.IndexWriterConfig config)

Parameters

Type	Name	Description
Store.Directory	directory	the on top of which an should be opened.
Index.IndexWriterConfig	config	configuration for the internal index writer.

Returns

Type	Description
Index.IndexWriter

See Also

CreateIndexWriterConfig(Index.OpenMode)

PrepareCommit()

prepare most of the work needed for a two-phase commit. See .

Declaration

public virtual void PrepareCommit()

ReplaceTaxonomy(Store.Directory)

Replaces the current taxonomy with the given one. This method should generally be called in conjunction with to replace both the taxonomy as well as the search index content.

Declaration

public virtual void ReplaceTaxonomy(Store.Directory taxoDir)

Parameters

Type	Name	Description
Store.Directory	taxoDir

Rollback()

Rollback changes to the taxonomy writer and closes the instance. Following this method the instance becomes unusable (calling any of its API methods will yield an ).

Declaration

public virtual void Rollback()

SetCacheMissesUntilFill(Int32)

Set the number of cache misses before an attempt is made to read the entire taxonomy into the in-memory cache.

This taxonomy writer holds an in-memory cache of recently seen categories to speed up operation. On each cache-miss, the on-disk index needs to be consulted. When an existing taxonomy is opened, a lot of slow disk reads like that are needed until the cache is filled, so it is more efficient to read the entire taxonomy into memory at once. We do this complete read after a certain number (defined by this method) of cache misses.

If the number is set to 0, the entire taxonomy is read into the cache on first use, without fetching individual categories first.

NOTE: it is assumed that this method is called immediately after the taxonomy writer has been created.

Declaration

public virtual void SetCacheMissesUntilFill(int i)

Parameters

Type	Name	Description
System.Int32	i

SetCommitData(IDictionary<String, String>)

Declaration

public virtual void SetCommitData(IDictionary<string, string> commitUserData)

Parameters

Type	Name	Description
IDictionary<System.String, System.String>	commitUserData

Unlock(Store.Directory)

Forcibly unlocks the taxonomy in the named directory.

Caution: this should only be used by failure recovery code, when it is known that no other process nor thread is in fact currently accessing this taxonomy.

This method is unnecessary if your uses a instead of the default . When the "native" lock is used, a lock does not stay behind forever when the process using it dies.

Declaration

public static void Unlock(Store.Directory directory)

Parameters

Type	Name	Description
Store.Directory	directory

Implements

ITaxonomyWriter

IDisposable

ITwoPhaseCommit