org.apache.lucene.index
Class SnapshotDeletionPolicy

java.lang.Object
  org.apache.lucene.index.SnapshotDeletionPolicy

All Implemented Interfaces:

IndexDeletionPolicy

Direct Known Subclasses:

PersistentSnapshotDeletionPolicy

public class SnapshotDeletionPolicy
extends Object
implements IndexDeletionPolicy

An IndexDeletionPolicy that wraps around 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 persistency is important, you can use PersistentSnapshotDeletionPolicy (or your own extension) and when creating a new instance of this deletion policy, pass the persistent snapshots information to SnapshotDeletionPolicy(IndexDeletionPolicy, Map).

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

Nested Class Summary

protected class

SnapshotDeletionPolicy.SnapshotCommitPoint

Field Summary

protected IndexCommit

lastCommit

Constructor Summary

SnapshotDeletionPolicy(IndexDeletionPolicy primary)

SnapshotDeletionPolicy(IndexDeletionPolicy primary, Map<String,String> snapshotsInfo)
SnapshotDeletionPolicy wraps another IndexDeletionPolicy to enable flexible snapshotting.

Method Summary

protected void	checkSnapshotted(String id) Checks if the given id is already used by another snapshot, and throws IllegalStateException if it is.
IndexCommit	getSnapshot(String id) Get a snapshotted IndexCommit by ID.
Map<String,String>	getSnapshots() Get all the snapshots in a map of snapshot IDs to the segments they 'cover.' This can be passed to SnapshotDeletionPolicy(IndexDeletionPolicy, Map) in order to initialize snapshots at construction.
boolean	isSnapshotted(String id) Returns true if the given ID is already used by a snapshot.
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.
protected void	registerSnapshotInfo(String id, String segment, IndexCommit commit) Registers the given snapshot information.
void	release(String id) Release a snapshotted commit by ID.
IndexCommit	snapshot(String id) Snapshots the last commit.
protected List<IndexCommit>	wrapCommits(List<? extends IndexCommit> commits)

Methods inherited from class java.lang.Object

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

Field Detail

lastCommit

protected IndexCommit lastCommit

Constructor Detail

SnapshotDeletionPolicy

public SnapshotDeletionPolicy(IndexDeletionPolicy primary)

SnapshotDeletionPolicy

public SnapshotDeletionPolicy(IndexDeletionPolicy primary,
                              Map<String,String> snapshotsInfo)

SnapshotDeletionPolicy wraps another IndexDeletionPolicy to enable flexible snapshotting.

Parameters:

primary - the IndexDeletionPolicy that is used on non-snapshotted commits. Snapshotted commits, are not deleted until explicitly released via release(String)

snapshotsInfo - A mapping of snapshot ID to the segments filename that is being snapshotted. The expected input would be the output of getSnapshots(). A null value signals that there are no initial snapshots to maintain.

Method Detail

checkSnapshotted

protected void checkSnapshotted(String id)

Checks if the given id is already used by another snapshot, and throws IllegalStateException if it is.

registerSnapshotInfo

protected void registerSnapshotInfo(String id,
                                    String segment,
                                    IndexCommit commit)

Registers the given snapshot information.

wrapCommits

protected List<IndexCommit> wrapCommits(List<? extends IndexCommit> commits)

getSnapshot

public IndexCommit getSnapshot(String id)

Get a snapshotted IndexCommit by ID. The IndexCommit can then be used to open an IndexReader on a specific commit point, or rollback the index by opening an IndexWriter with the IndexCommit specified in its IndexWriterConfig.

Parameters:

id - a unique identifier of the commit that was snapshotted.

Returns:

The IndexCommit for this particular snapshot.

Throws:

IllegalStateException - if no snapshot exists by the specified ID.

getSnapshots

public Map<String,String> getSnapshots()

Get all the snapshots in a map of snapshot IDs to the segments they 'cover.' This can be passed to SnapshotDeletionPolicy(IndexDeletionPolicy, Map) in order to initialize snapshots at construction.

isSnapshotted

public boolean isSnapshotted(String id)

Returns true if the given ID is already used by a snapshot. You can call this method before snapshot(String) if you are not sure whether the ID is already used or not.

onCommit

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

Description copied from interface: 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 interface 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 interface: 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 interface IndexDeletionPolicy

Parameters:

commits - List of current point-in-time commits, sorted by age (the 0th one is the oldest commit).

Throws:

IOException

release

public void release(String id)
             throws IOException

Release a snapshotted commit by ID.

Parameters:

id - a unique identifier of the commit that is un-snapshotted.

Throws:

IllegalStateException - if no snapshot exists by this ID.

IOException

snapshot

public IndexCommit snapshot(String id)
                     throws IOException

Snapshots the last commit. Once a commit is 'snapshotted,' it is protected from deletion (as long as this IndexDeletionPolicy is used). The commit can be removed by calling release(String) using the same ID parameter followed by a call to IndexWriter.deleteUnusedFiles().

NOTE: ID must be unique in the system. If the same ID is used twice, an IllegalStateException is thrown.

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.

Parameters:

id - a unique identifier of the commit that is being snapshotted.

Returns:

the IndexCommit that was snapshotted.

Throws:

IllegalStateException - if either there is no 'last commit' to snapshot, or if the parameter 'ID' refers to an already snapshotted commit.

IOException