From d6f39b29b73c1f454aec9158100f314dddfd1c3f Mon Sep 17 00:00:00 2001 From: Michael McCandless Date: Thu, 30 Oct 2008 16:33:40 +0000 Subject: [PATCH] update javadocs to clarify how IndexWriter handles hitting an OOME git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@709198 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/lucene/index/IndexWriter.java | 152 ++++++++++++++++-- 1 file changed, 141 insertions(+), 11 deletions(-) diff --git a/src/java/org/apache/lucene/index/IndexWriter.java b/src/java/org/apache/lucene/index/IndexWriter.java index 2761626a74a..f6f1ae1150f 100644 --- a/src/java/org/apache/lucene/index/IndexWriter.java +++ b/src/java/org/apache/lucene/index/IndexWriter.java @@ -179,6 +179,19 @@ import java.util.Iterator; MergeScheduler} is invoked with the requested merges and it decides when and how to run the merges. The default is {@link ConcurrentMergeScheduler}.

+ +

NOTE: if you hit an + OutOfMemoryError then IndexWriter will quietly record this + fact and block all future segment commits. This is a + defensive measure in case any internal state (buffered + documents and deletions) were corrupted. Any subsequent + calls to {@link #commit()} will throw an + IllegalStateException. The only course of action is to + call {@link #close()}, which internally will call {@link + #rollback()}, to undo any changes to the index since the + last commit. If you opened the writer with autoCommit + false you can also just call {@link #rollback()} + directly.

*/ /* @@ -1655,6 +1668,11 @@ public class IndexWriter { * * after which, you must be certain not to use the writer * instance anymore.

+ * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer, again. See above for details.

+ * * @throws CorruptIndexException if the index is corrupt * @throws IOException if there is a low-level IO error */ @@ -1667,6 +1685,11 @@ public class IndexWriter { * running merges to finish. This is only meaningful when * using a MergeScheduler that runs merges in background * threads. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @param waitForMerges if true, this call will block * until all merges complete; else, it will ask all * running merges to abort, wait until those merges have @@ -1972,6 +1995,10 @@ public class IndexWriter { * replaced with the Unicode replacement character * U+FFFD.

* + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @throws CorruptIndexException if the index is corrupt * @throws IOException if there is a low-level IO error */ @@ -1989,6 +2016,10 @@ public class IndexWriter { * index and IndexWriter state after an Exception, and * flushing/merging temporary free space requirements.

* + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @throws CorruptIndexException if the index is corrupt * @throws IOException if there is a low-level IO error */ @@ -2027,6 +2058,11 @@ public class IndexWriter { /** * Deletes the document(s) containing term. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @param term the term to identify the documents to be deleted * @throws CorruptIndexException if the index is corrupt * @throws IOException if there is a low-level IO error @@ -2046,6 +2082,11 @@ public class IndexWriter { /** * Deletes the document(s) containing any of the * terms. All deletes are flushed at the same time. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @param terms array of terms to identify the documents * to be deleted * @throws CorruptIndexException if the index is corrupt @@ -2065,6 +2106,11 @@ public class IndexWriter { /** * Deletes the document(s) matching the provided query. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @param query the query to identify the documents to be deleted * @throws CorruptIndexException if the index is corrupt * @throws IOException if there is a low-level IO error @@ -2079,6 +2125,11 @@ public class IndexWriter { /** * Deletes the document(s) matching any of the provided queries. * All deletes are flushed at the same time. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @param queries array of queries to identify the documents * to be deleted * @throws CorruptIndexException if the index is corrupt @@ -2097,6 +2148,11 @@ public class IndexWriter { * document. The delete and then add are atomic as seen * by a reader on the same index (flush may happen only after * the add). + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @param term the term to identify the document(s) to be * deleted * @param doc the document to be added @@ -2114,6 +2170,11 @@ public class IndexWriter { * document. The delete and then add are atomic as seen * by a reader on the same index (flush may happen only after * the add). + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @param term the term to identify the document(s) to be * deleted * @param doc the document to be added @@ -2208,8 +2269,6 @@ public class IndexWriter { * default merge policy, but individaul merge policies may implement * optimize in different ways. * - * @see LogMergePolicy#findMergesForOptimize - * *

It is recommended that this method be called upon completion of indexing. In * environments with frequent updates, optimize is best done during low volume times, if at all. * @@ -2275,8 +2334,13 @@ public class IndexWriter { * newly created segments will not be optimized unless you * call optimize again.

* + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @throws CorruptIndexException if the index is corrupt * @throws IOException if there is a low-level IO error + * @see LogMergePolicy#findMergesForOptimize */ public void optimize() throws CorruptIndexException, IOException { optimize(true); @@ -2286,6 +2350,11 @@ public class IndexWriter { * Optimize the index down to <= maxNumSegments. If * maxNumSegments==1 then this is the same as {@link * #optimize()}. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @param maxNumSegments maximum number of segments left * in the index after optimization finishes */ @@ -2297,7 +2366,12 @@ public class IndexWriter { * whether the call should block until the optimize * completes. This is only meaningful with a * {@link MergeScheduler} that is able to run merges in - * background threads. */ + * background threads. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ */ public void optimize(boolean doWait) throws CorruptIndexException, IOException { optimize(1, doWait); } @@ -2306,7 +2380,12 @@ public class IndexWriter { * specify whether the call should block until the * optimize completes. This is only meaningful with a * {@link MergeScheduler} that is able to run merges in - * background threads. */ + * background threads. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ */ public void optimize(int maxNumSegments, boolean doWait) throws CorruptIndexException, IOException { ensureOpen(); @@ -2402,7 +2481,12 @@ public class IndexWriter { * specify whether the call should block until the * operation completes. This is only meaningful with a * {@link MergeScheduler} that is able to run merges in - * background threads. */ + * background threads. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ */ public void expungeDeletes(boolean doWait) throws CorruptIndexException, IOException { ensureOpen(); @@ -2473,7 +2557,12 @@ public class IndexWriter { * MergePolicy#findMergesToExpungeDeletes}.). Note that * this call does not first commit any buffered * documents, so you must do so yourself if necessary. - * See also {@link #expungeDeletes(boolean)} */ + * See also {@link #expungeDeletes(boolean)} + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ */ public void expungeDeletes() throws CorruptIndexException, IOException { expungeDeletes(true); } @@ -2487,6 +2576,10 @@ public class IndexWriter { * Explicit calls to maybeMerge() are usually not * necessary. The most common case is when merge policy * parameters have changed. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

*/ public final void maybeMerge() throws CorruptIndexException, IOException { maybeMerge(false); @@ -2927,9 +3020,15 @@ public class IndexWriter { } /** Merges all segments from an array of indexes into this index. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @deprecated Use {@link #addIndexesNoOptimize} instead, * then separately call {@link #optimize} afterwards if * you need to. + * * @throws CorruptIndexException if the index is corrupt * @throws IOException if there is a low-level IO error */ @@ -3050,6 +3149,10 @@ public class IndexWriter { *

* This requires this index not be among those to be added. * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @throws CorruptIndexException if the index is corrupt * @throws IOException if there is a low-level IO error */ @@ -3233,6 +3336,11 @@ public class IndexWriter { * details on transactional semantics, temporary free * space required in the Directory, and non-CFS segments * on an Exception.

+ * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @throws CorruptIndexException if the index is corrupt * @throws IOException if there is a low-level IO error */ @@ -3391,9 +3499,15 @@ public class IndexWriter { *

Note: while this will force buffered docs to be * pushed into the index, it will not make these docs * visible to a reader. Use {@link #commit()} instead + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * + * @deprecated please call {@link #commit()}) instead + * * @throws CorruptIndexException if the index is corrupt * @throws IOException if there is a low-level IO error - * @deprecated please call {@link #commit()}) instead */ public final void flush() throws CorruptIndexException, IOException { if (hitOOM) @@ -3403,6 +3517,11 @@ public class IndexWriter { } /** Expert: prepare for commit. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @see #prepareCommit(String) */ public final void prepareCommit() throws CorruptIndexException, IOException { ensureOpen(); @@ -3425,6 +3544,10 @@ public class IndexWriter { * without prepareCommit first in which case that method * will internally call prepareCommit. * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @param commitUserData Opaque String that's recorded * into the segments file in the index, and retrievable * by {@link IndexReader#getCommitUserData}. Note that @@ -3500,11 +3623,13 @@ public class IndexWriter { * loss it may still lose data. Lucene cannot guarantee * consistency on such devices.

* + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ * * @see #prepareCommit + * @see #commit(String) */ - - /** Commits all changes to the index. - * @see #commit(String) */ public final void commit() throws CorruptIndexException, IOException { commit(null); } @@ -3512,7 +3637,12 @@ public class IndexWriter { /** Commits all changes to the index, specifying a * commitUserData String. This just calls {@link * #prepareCommit(String)} (if you didn't already call - * it) and then {@link #finishCommit}. */ + * it) and then {@link #finishCommit}. + * + *

NOTE: if this method hits an OutOfMemoryError + * you should immediately close the writer. See above for details.

+ */ public final void commit(String commitUserData) throws CorruptIndexException, IOException { ensureOpen();