Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.lucene.index; import java.util.Collection; import java.util.HashMap; import java.util.List; import java.util.ArrayList; import java.util.Map; import java.io.IOException; import org.apache.lucene.store.Directory; /** * An {@link IndexDeletionPolicy} that wraps any other * {@link IndexDeletionPolicy} and adds the ability to hold and later release * snapshots of an index. While a snapshot is held, the {@link IndexWriter} will * not remove any files associated with it even if the index is otherwise being * actively, arbitrarily changed. Because we wrap another arbitrary * {@link IndexDeletionPolicy}, this gives you the freedom to continue using * whatever {@link IndexDeletionPolicy} you would normally want to use with your * index. * * <p> * 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 {@link PersistentSnapshotDeletionPolicy}. * * @lucene.experimental */ public class SnapshotDeletionPolicy extends IndexDeletionPolicy { /** Records how many snapshots are held against each * commit generation */ protected final Map<Long, Integer> refCounts = new HashMap<>(); /** Used to map gen to IndexCommit. */ protected final Map<Long, IndexCommit> indexCommits = new HashMap<>(); /** Wrapped {@link IndexDeletionPolicy} */ private final IndexDeletionPolicy primary; /** Most recently committed {@link IndexCommit}. */ protected IndexCommit lastCommit; /** Used to detect misuse */ private boolean initCalled; /** Sole constructor, taking the incoming {@link * IndexDeletionPolicy} to wrap. */ public SnapshotDeletionPolicy(IndexDeletionPolicy primary) { this.primary = primary; } @Override public synchronized void onCommit(List<? extends IndexCommit> commits) throws IOException { primary.onCommit(wrapCommits(commits)); lastCommit = commits.get(commits.size() - 1); } @Override public synchronized void onInit(List<? extends IndexCommit> commits) throws IOException { initCalled = true; primary.onInit(wrapCommits(commits)); for (IndexCommit commit : commits) { if (refCounts.containsKey(commit.getGeneration())) { indexCommits.put(commit.getGeneration(), commit); } } if (!commits.isEmpty()) { lastCommit = commits.get(commits.size() - 1); } } /** * Release a snapshotted commit. * * @param commit * the commit previously returned by {@link #snapshot} */ public synchronized void release(IndexCommit commit) throws IOException { long gen = commit.getGeneration(); releaseGen(gen); } /** Release a snapshot by generation. */ protected void releaseGen(long gen) throws IOException { if (!initCalled) { throw new IllegalStateException( "this instance is not being used by IndexWriter; be sure to use the instance returned from writer.getConfig().getIndexDeletionPolicy()"); } Integer refCount = refCounts.get(gen); if (refCount == null) { throw new IllegalArgumentException("commit gen=" + gen + " is not currently snapshotted"); } int refCountInt = refCount.intValue(); assert refCountInt > 0; refCountInt--; if (refCountInt == 0) { refCounts.remove(gen); indexCommits.remove(gen); } else { refCounts.put(gen, refCountInt); } } /** Increments the refCount for this {@link IndexCommit}. */ protected synchronized void incRef(IndexCommit ic) { long gen = ic.getGeneration(); Integer refCount = refCounts.get(gen); int refCountInt; if (refCount == null) { indexCommits.put(gen, lastCommit); refCountInt = 0; } else { refCountInt = refCount.intValue(); } refCounts.put(gen, refCountInt + 1); } /** * Snapshots the last commit and returns it. Once a commit is 'snapshotted,' it is protected * from deletion (as long as this {@link IndexDeletionPolicy} is used). The * snapshot can be removed by calling {@link #release(IndexCommit)} followed * by a call to {@link IndexWriter#deleteUnusedFiles()}. * * <p> * <b>NOTE:</b> 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. * * @throws IllegalStateException * if this index does not have any commits yet * @return the {@link IndexCommit} that was snapshotted. */ public synchronized IndexCommit snapshot() throws IOException { if (!initCalled) { throw new IllegalStateException( "this instance is not being used by IndexWriter; be sure to use the instance returned from writer.getConfig().getIndexDeletionPolicy()"); } if (lastCommit == null) { // No commit yet, eg this is a new IndexWriter: throw new IllegalStateException("No index commit to snapshot"); } incRef(lastCommit); return lastCommit; } /** Returns all IndexCommits held by at least one snapshot. */ public synchronized List<IndexCommit> getSnapshots() { return new ArrayList<>(indexCommits.values()); } /** Returns the total number of snapshots currently held. */ public synchronized int getSnapshotCount() { int total = 0; for (Integer refCount : refCounts.values()) { total += refCount.intValue(); } return total; } /** Retrieve an {@link IndexCommit} from its generation; * returns null if this IndexCommit is not currently * snapshotted */ public synchronized IndexCommit getIndexCommit(long gen) { return indexCommits.get(gen); } /** Wraps each {@link IndexCommit} as a {@link * SnapshotCommitPoint}. */ private List<IndexCommit> wrapCommits(List<? extends IndexCommit> commits) { List<IndexCommit> wrappedCommits = new ArrayList<>(commits.size()); for (IndexCommit ic : commits) { wrappedCommits.add(new SnapshotCommitPoint(ic)); } return wrappedCommits; } /** Wraps a provided {@link IndexCommit} and prevents it * from being deleted. */ private class SnapshotCommitPoint extends IndexCommit { /** The {@link IndexCommit} we are preventing from deletion. */ protected IndexCommit cp; /** Creates a {@code SnapshotCommitPoint} wrapping the provided * {@link IndexCommit}. */ protected SnapshotCommitPoint(IndexCommit cp) { this.cp = cp; } @Override public String toString() { return "SnapshotDeletionPolicy.SnapshotCommitPoint(" + cp + ")"; } @Override public void delete() { synchronized (SnapshotDeletionPolicy.this) { // Suppress the delete request if this commit point is // currently snapshotted. if (!refCounts.containsKey(cp.getGeneration())) { cp.delete(); } } } @Override public Directory getDirectory() { return cp.getDirectory(); } @Override public Collection<String> getFileNames() throws IOException { return cp.getFileNames(); } @Override public long getGeneration() { return cp.getGeneration(); } @Override public String getSegmentsFileName() { return cp.getSegmentsFileName(); } @Override public Map<String, String> getUserData() throws IOException { return cp.getUserData(); } @Override public boolean isDeleted() { return cp.isDeleted(); } @Override public int getSegmentCount() { return cp.getSegmentCount(); } } }