SnapshotDeletionPolicy (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.index, class: SnapshotDeletionPolicy

Package 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
  Description
  `protected final Map<Long,IndexCommit>`
  `indexCommits`
  Used to map gen to IndexCommit.
  `protected IndexCommit`
  `lastCommit`
  Most recently committed `IndexCommit`.
  `protected final Map<Long,Integer>`
  `refCounts`
  Records how many snapshots are held against each commit generation

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  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 Details

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

  - ### SnapshotDeletionPolicy

    public SnapshotDeletionPolicy(IndexDeletionPolicy primary)
    Sole constructor, taking the incoming `IndexDeletionPolicy` to wrap.

- ## Method Details

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