Apache
/
lucene
mirror of https://github.com/apache/lucene.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

LUCENE-3023: cleaned up javadoc with respect to DWPT changes 

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/branches/realtime_search@1097381 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Simon Willnauer 2011-04-28 09:38:04 +00:00
parent 7e91c2bbde
commit f47c3e8298
2 changed files with 64 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
lucene/src/java/org/apache/lucene/index/IndexWriter.java
View File

@ -56,17 +56,16 @@ import org.apache.lucene.util.MapBackedSet;
/** /**
An <code>IndexWriter</code> creates and maintains an index. An <code>IndexWriter</code> creates and maintains an index.
<p>The <code>create</code> argument to the {@link <p>The {@link OpenMode} option on
#IndexWriter(Directory, IndexWriterConfig) constructor} determines {@link IndexWriterConfig#setOpenMode(OpenMode)} determines
whether a new index is created, or whether an existing index is whether a new index is created, or whether an existing index is
opened. Note that you can open an index with <code>create=true</code> opened. Note that you can open an index with {@link OpenMode#CREATE}
even while readers are using the index. The old readers will even while readers are using the index. The old readers will
continue to search the "point in time" snapshot they had opened, continue to search the "point in time" snapshot they had opened,
and won't see the newly created index until they re-open. There are and won't see the newly created index until they re-open. If
also {@link #IndexWriter(Directory, IndexWriterConfig) constructors} {@link OpenMode#CREATE_OR_APPEND} is used IndexWriter will create a
with no <code>create</code> argument which will create a new index new index if there is not already an index at the provided path
if there is not already an index at the provided path and otherwise and otherwise open the existing index.</p>
open the existing index.</p>
<p>In either case, documents are added with {@link #addDocument(Document) <p>In either case, documents are added with {@link #addDocument(Document)
addDocument} and removed with {@link #deleteDocuments(Term)} or {@link addDocument} and removed with {@link #deleteDocuments(Term)} or {@link
@ -78,15 +77,19 @@ import org.apache.lucene.util.MapBackedSet;
<a name="flush"></a> <a name="flush"></a>
<p>These changes are buffered in memory and periodically <p>These changes are buffered in memory and periodically
flushed to the {@link Directory} (during the above method flushed to the {@link Directory} (during the above method
calls). A flush is triggered when there are enough calls). A flush is triggered when there are enough added documents
buffered deletes (see {@link IndexWriterConfig#setMaxBufferedDeleteTerms}) since the last flush. Flushing is triggered either by RAM usage of the
or enough added documents since the last flush, whichever documents (see {@link IndexWriterConfig#setRAMBufferSizeMB}) or the
is sooner. For the added documents, flushing is triggered number of added documents (see {@link IndexWriterConfig#setMaxBufferedDocs(int)}).
either by RAM usage of the documents (see {@link The default is to flush when RAM usage hits
IndexWriterConfig#setRAMBufferSizeMB}) or the number of added documents. {@value IndexWriterConfig#DEFAULT_RAM_BUFFER_SIZE_MB} MB. For
The default is to flush when RAM usage hits 16 MB. For
best indexing speed you should flush by RAM usage with a best indexing speed you should flush by RAM usage with a
large RAM buffer. Note that flushing just moves the large RAM buffer. Additionally, if IndexWriter reaches the configured number of
buffered deletes (see {@link IndexWriterConfig#setMaxBufferedDeleteTerms})
the deleted terms and queries are flushed and applied to existing segments.
In contrast to the other flush options {@link IndexWriterConfig#setRAMBufferSizeMB} and
{@link IndexWriterConfig#setMaxBufferedDocs(int)}, deleted terms
won't trigger a segment flush. Note that flushing just moves the
internal buffered state in IndexWriter into the index, but internal buffered state in IndexWriter into the index, but
these changes are not visible to IndexReader until either these changes are not visible to IndexReader until either
{@link #commit()} or {@link #close} is called. A flush may {@link #commit()} or {@link #close} is called. A flush may
@ -1247,7 +1250,8 @@ public class IndexWriter implements Closeable {
/** /**
* Deletes the document(s) containing any of the * Deletes the document(s) containing any of the
* terms. All deletes are flushed at the same time. * terms. All given deletes are applied and flushed atomically
* at the same time.
* *
* <p><b>NOTE</b>: if this method hits an OutOfMemoryError * <p><b>NOTE</b>: if this method hits an OutOfMemoryError
* you should immediately close the writer. See <a * you should immediately close the writer. See <a
@ -1289,7 +1293,7 @@ public class IndexWriter implements Closeable {
/** /**
* Deletes the document(s) matching any of the provided queries. * Deletes the document(s) matching any of the provided queries.
* All deletes are flushed at the same time. * All given deletes are applied and flushed atomically at the same time.
* *
* <p><b>NOTE</b>: if this method hits an OutOfMemoryError * <p><b>NOTE</b>: if this method hits an OutOfMemoryError
* you should immediately close the writer. See <a * you should immediately close the writer. See <a

60
lucene/src/java/org/apache/lucene/index/IndexWriterConfig.java
View File

@ -348,12 +348,12 @@ public final class IndexWriterConfig implements Cloneable {
/** /**
* Determines the minimal number of delete terms required before the buffered * Determines the minimal number of delete terms required before the buffered
* in-memory delete terms are applied and flushed. If there are documents * in-memory delete terms and queries are applied and flushed.
* buffered in memory at the time, they are merged and a new segment is * <p>Disabled by default (writer flushes by RAM usage).</p>
* created. * <p>
* NOTE: This setting won't trigger a segment flush.
* <p>Disabled by default (writer flushes by RAM usage). * </p>
* *
* @throws IllegalArgumentException if maxBufferedDeleteTerms * @throws IllegalArgumentException if maxBufferedDeleteTerms
* is enabled but smaller than 1 * is enabled but smaller than 1
* @see #setRAMBufferSizeMB * @see #setRAMBufferSizeMB
@ -372,8 +372,8 @@ public final class IndexWriterConfig implements Cloneable {
} }
/** /**
* Returns the number of buffered deleted terms that will trigger a flush if * Returns the number of buffered deleted terms that will trigger a flush of all
* enabled. * buffered deletes if enabled.
* *
* @see #setMaxBufferedDeleteTerms(int) * @see #setMaxBufferedDeleteTerms(int)
*/ */
@ -406,8 +406,10 @@ public final class IndexWriterConfig implements Cloneable {
* way to measure the RAM usage of individual Queries so the accounting will * way to measure the RAM usage of individual Queries so the accounting will
* under-estimate and you should compensate by either calling commit() * under-estimate and you should compensate by either calling commit()
* periodically yourself, or by using {@link #setMaxBufferedDeleteTerms(int)} * periodically yourself, or by using {@link #setMaxBufferedDeleteTerms(int)}
* to flush by count instead of RAM usage (each buffered delete Query counts * to flush and apply buffered deletes by count instead of RAM usage
* as one). * (for each buffered delete Query a constant number of bytes is used to estimate
* RAM usage). Note that enabling {@link #setMaxBufferedDeleteTerms(int)} will
* not trigger any segment flushes.
* <p> * <p>
* <b>NOTE</b>: It's not guaranteed that all memory resident documents are flushed * <b>NOTE</b>: It's not guaranteed that all memory resident documents are flushed
* once this limit is exceeded. Depending on the configured {@link FlushPolicy} only a * once this limit is exceeded. Depending on the configured {@link FlushPolicy} only a
@ -417,6 +419,7 @@ public final class IndexWriterConfig implements Cloneable {
* *
* The default value is {@link #DEFAULT_RAM_BUFFER_SIZE_MB}. * The default value is {@link #DEFAULT_RAM_BUFFER_SIZE_MB}.
* @see #setFlushPolicy(FlushPolicy) * @see #setFlushPolicy(FlushPolicy)
* @see #setRAMPerThreadHardLimitMB(int)
* *
* <p>Takes effect immediately, but only the next time a * <p>Takes effect immediately, but only the next time a
* document is added, updated or deleted. * document is added, updated or deleted.
@ -537,24 +540,43 @@ public final class IndexWriterConfig implements Cloneable {
return mergePolicy; return mergePolicy;
} }
/** /** Expert: Sets the {@link DocumentsWriterPerThreadPool} instance used by the
* Sets the max number of simultaneous threads that may be indexing documents * IndexWriter to assign thread-states to incoming indexing threads. If no
* at once in IndexWriter. Values &lt; 1 are invalid and if passed * {@link DocumentsWriterPerThreadPool} is set {@link IndexWriter} will use
* <code>maxThreadStates</code> will be set to * {@link ThreadAffinityDocumentsWriterThreadPool} with max number of
* {@link #DEFAULT_MAX_THREAD_STATES}. * thread-states set to {@value #DEFAULT_MAX_THREAD_STATES} (see
* * {@link #DEFAULT_MAX_THREAD_STATES}).
* <p>Only takes effect when IndexWriter is first created. */ * </p>
* <p>
* NOTE: The given {@link DocumentsWriterPerThreadPool} instance must not be used with
* other {@link IndexWriter} instances once it has been initialized / associated with an
* {@link IndexWriter}.
* </p>
* <p>
* NOTE: This only takes effect when IndexWriter is first created.</p>*/
public IndexWriterConfig setIndexerThreadPool(DocumentsWriterPerThreadPool threadPool) { public IndexWriterConfig setIndexerThreadPool(DocumentsWriterPerThreadPool threadPool) {
if(threadPool == null) {
throw new IllegalArgumentException("DocumentsWriterPerThreadPool must not be nul");
}
this.indexerThreadPool = threadPool; this.indexerThreadPool = threadPool;
return this; return this;
} }
/** Returns the configured {@link DocumentsWriterPerThreadPool} instance.
* @see #setIndexerThreadPool(DocumentsWriterPerThreadPool)
* @return the configured {@link DocumentsWriterPerThreadPool} instance.*/
public DocumentsWriterPerThreadPool getIndexerThreadPool() { public DocumentsWriterPerThreadPool getIndexerThreadPool() {
return this.indexerThreadPool; return this.indexerThreadPool;
} }
/** Returns the max number of simultaneous threads that /** Returns the max number of simultaneous threads that may be indexing
* may be indexing documents at once in IndexWriter. */ * documents at once in IndexWriter.
* <p>
* To modify the max number of thread-states a new
* {@link DocumentsWriterPerThreadPool} must be set via
* {@link #setIndexerThreadPool(DocumentsWriterPerThreadPool)}.
* </p>
* @see #setIndexerThreadPool(DocumentsWriterPerThreadPool) */
public int getMaxThreadStates() { public int getMaxThreadStates() {
return indexerThreadPool.getMaxThreadStates(); return indexerThreadPool.getMaxThreadStates();
} }