001: package org.apache.lucene.index;
002:
003: /**
004: * Licensed to the Apache Software Foundation (ASF) under one or more
005: * contributor license agreements. See the NOTICE file distributed with
006: * this work for additional information regarding copyright ownership.
007: * The ASF licenses this file to You under the Apache License, Version 2.0
008: * (the "License"); you may not use this file except in compliance with
009: * the License. You may obtain a copy of the License at
010: *
011: * http://www.apache.org/licenses/LICENSE-2.0
012: *
013: * Unless required by applicable law or agreed to in writing, software
014: * distributed under the License is distributed on an "AS IS" BASIS,
015: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: * See the License for the specific language governing permissions and
017: * limitations under the License.
018: */
019:
020: import java.util.List;
021: import java.io.IOException;
022:
023: /**
024: * <p>Expert: policy for deletion of stale {@link IndexCommitPoint index commits}.
025: *
026: * <p>Implement this interface, and pass it to one
027: * of the {@link IndexWriter} or {@link IndexReader}
028: * constructors, to customize when older
029: * {@link IndexCommitPoint point-in-time commits}
030: * are deleted from the index directory. The default deletion policy
031: * is {@link KeepOnlyLastCommitDeletionPolicy}, which always
032: * removes old commits as soon as a new commit is done (this
033: * matches the behavior before 2.2).</p>
034: *
035: * <p>One expected use case for this (and the reason why it
036: * was first created) is to work around problems with an
037: * index directory accessed via filesystems like NFS because
038: * NFS does not provide the "delete on last close" semantics
039: * that Lucene's "point in time" search normally relies on.
040: * By implementing a custom deletion policy, such as "a
041: * commit is only removed once it has been stale for more
042: * than X minutes", you can give your readers time to
043: * refresh to the new commit before {@link IndexWriter}
044: * removes the old commits. Note that doing so will
045: * increase the storage requirements of the index. See <a
046: * target="top"
047: * href="http://issues.apache.org/jira/browse/LUCENE-710">LUCENE-710</a>
048: * for details.</p>
049: */
050:
051: public interface IndexDeletionPolicy {
052:
053: /**
054: * <p>This is called once when a writer is first
055: * instantiated to give the policy a chance to remove old
056: * commit points.</p>
057: *
058: * <p>The writer locates all index commits present in the
059: * index directory and calls this method. The policy may
060: * choose to delete some of the commit points, doing so by
061: * calling method {@link IndexCommitPoint#delete delete()}
062: * of {@link IndexCommitPoint}.</p>
063: *
064: * <p><u>Note:</u> the last CommitPoint is the most recent one,
065: * i.e. the "front index state". Be careful not to delete it,
066: * unless you know for sure what you are doing, and unless
067: * you can afford to lose the index content while doing that.
068: *
069: * @param commits List of current
070: * {@link IndexCommitPoint point-in-time commits},
071: * sorted by age (the 0th one is the oldest commit).
072: */
073: public void onInit(List commits) throws IOException;
074:
075: /**
076: * <p>This is called each time the writer completed a commit.
077: * This gives the policy a chance to remove old commit points
078: * with each commit.</p>
079: *
080: * <p>The policy may now choose to delete old commit points
081: * by calling method {@link IndexCommitPoint#delete delete()}
082: * of {@link IndexCommitPoint}.</p>
083: *
084: * <p>If writer has <code>autoCommit = true</code> then
085: * this method will in general be called many times during
086: * one instance of {@link IndexWriter}. If
087: * <code>autoCommit = false</code> then this method is
088: * only called once when {@link IndexWriter#close} is
089: * called, or not at all if the {@link IndexWriter#abort}
090: * is called.
091: *
092: * <p><u>Note:</u> the last CommitPoint is the most recent one,
093: * i.e. the "front index state". Be careful not to delete it,
094: * unless you know for sure what you are doing, and unless
095: * you can afford to lose the index content while doing that.
096: *
097: * @param commits List of {@link IndexCommitPoint},
098: * sorted by age (the 0th one is the oldest commit).
099: */
100: public void onCommit(List commits) throws IOException;
101: }
|