org.apache.lucene.index

Class SnapshotDeletionPolicy

java.lang.Object

org.apache.lucene.index.IndexDeletionPolicy

org.apache.lucene.index.SnapshotDeletionPolicy

Direct Known Subclasses:

PersistentSnapshotDeletionPolicy

public class SnapshotDeletionPolicy
extends IndexDeletionPolicy

An IndexDeletionPolicy that wraps any other IndexDeletionPolicy and adds the ability to hold and later release snapshots of an index. While a snapshot is held, the IndexWriter will not remove any files associated with it even if the index is otherwise being actively, arbitrarily changed. Because we wrap another arbitrary IndexDeletionPolicy, this gives you the freedom to continue using whatever IndexDeletionPolicy you would normally want to use with your index.

This class maintains all snapshots in-memory, and so the information is not persisted and not protected against system failures. If persistence is important, you can use PersistentSnapshotDeletionPolicy.

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

Field Summary

Fields

Modifier and Type	Field and Description
protected Map<Long,IndexCommit>	indexCommits Used to map gen to IndexCommit.
protected IndexCommit	lastCommit Most recently committed IndexCommit.
protected Map<Long,Integer>	refCounts Records how many snapshots are held against each commit generation

Constructor Summary

Constructors

Constructor and Description
SnapshotDeletionPolicy(IndexDeletionPolicy primary) Sole constructor, taking the incoming IndexDeletionPolicy to wrap.

Method Summary

Modifier and Type	Method and Description
IndexCommit	getIndexCommit(long gen) Retrieve an IndexCommit from its generation; returns null if this IndexCommit is not currently snapshotted
int	getSnapshotCount() Returns the total number of snapshots currently held.
List<IndexCommit>	getSnapshots() Returns all IndexCommits held by at least one snapshot.
protected void	incRef(IndexCommit ic) Increments the refCount for this IndexCommit.
void	onCommit(List<? extends IndexCommit> commits) This is called each time the writer completed a commit.
void	onInit(List<? extends IndexCommit> commits) This is called once when a writer is first instantiated to give the policy a chance to remove old commit points.
void	release(IndexCommit commit) Release a snapshotted commit.
protected void	releaseGen(long gen) Release a snapshot by generation.
IndexCommit	snapshot() Snapshots the last commit and returns it.

Methods inherited from class java.lang.Object

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

Field Detail

refCounts

protected final Map<Long,Integer> refCounts

Records how many snapshots are held against each commit generation

indexCommits

protected final Map<Long,IndexCommit> indexCommits

Used to map gen to IndexCommit.

lastCommit

protected IndexCommit lastCommit

Most recently committed IndexCommit.

Constructor Detail

SnapshotDeletionPolicy

public SnapshotDeletionPolicy(IndexDeletionPolicy primary)

Sole constructor, taking the incoming IndexDeletionPolicy to wrap.

Method Detail

onCommit

public void onCommit(List<? extends IndexCommit> commits)
              throws IOException

Description copied from class: IndexDeletionPolicy

This is called each time the writer completed a commit. This gives the policy a chance to remove old commit points with each commit.

The policy may now choose to delete old commit points by calling method delete() of IndexCommit.

This method is only called when IndexWriter.commit() or IndexWriter.close() is called, or possibly not at all if the IndexWriter.rollback() is called.

Note: the last CommitPoint is the most recent one, i.e. the "front index state". Be careful not to delete it, unless you know for sure what you are doing, and unless you can afford to lose the index content while doing that.

Specified by:

onCommit in class IndexDeletionPolicy

Parameters:

commits - List of IndexCommit, sorted by age (the 0th one is the oldest commit).

Throws:

IOException

onInit

public void onInit(List<? extends IndexCommit> commits)
            throws IOException

Description copied from class: IndexDeletionPolicy

This is called once when a writer is first instantiated to give the policy a chance to remove old commit points.

The writer locates all index commits present in the index directory and calls this method. The policy may choose to delete some of the commit points, doing so by calling method delete() of IndexCommit.

Note: the last CommitPoint is the most recent one, i.e. the "front index state". Be careful not to delete it, unless you know for sure what you are doing, and unless you can afford to lose the index content while doing that.

Specified by:

onInit in class IndexDeletionPolicy

Parameters:

commits - List of current point-in-time commits, sorted by age (the 0th one is the oldest commit). Note that for a new index this method is invoked with an empty list.

Throws:

IOException

release

public void release(IndexCommit commit)
             throws IOException

Release a snapshotted commit.

Parameters:

commit - the commit previously returned by snapshot()

Throws:

IOException

releaseGen

protected void releaseGen(long gen)
                   throws IOException

Release a snapshot by generation.

Throws:

IOException

incRef

protected void incRef(IndexCommit ic)

Increments the refCount for this IndexCommit.

snapshot

public IndexCommit snapshot()
                     throws IOException

Snapshots the last commit and returns it. Once a commit is 'snapshotted,' it is protected from deletion (as long as this IndexDeletionPolicy is used). The snapshot can be removed by calling release(IndexCommit) followed by a call to IndexWriter.deleteUnusedFiles().

NOTE: while the snapshot is held, the files it references will not be deleted, which will consume additional disk space in your index. If you take a snapshot at a particularly bad time (say just before you call forceMerge) then in the worst case this could consume an extra 1X of your total index size, until you release the snapshot.

Returns:

the IndexCommit that was snapshotted.

Throws:

IllegalStateException - if this index does not have any commits yet

IOException

getSnapshots

public List<IndexCommit> getSnapshots()

Returns all IndexCommits held by at least one snapshot.

getSnapshotCount

public int getSnapshotCount()

Returns the total number of snapshots currently held.

getIndexCommit

public IndexCommit getIndexCommit(long gen)

Retrieve an IndexCommit from its generation; returns null if this IndexCommit is not currently snapshotted