## 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`