svn commit: r1369023 - in /lucene/dev/branches/branch_4x: ./ lucene/ lucene/core/ lucene/core/src/java/org/apache/lucene/index/DirectoryReader.java lucene/core/src/java/org/apache/lucene/index/LiveIndexWriterConfig.java

[rm...@apache.org]

Author: rmuir
Date: Fri Aug  3 15:21:02 2012
New Revision: 1369023

URL: http://svn.apache.org/viewvc?rev=1369023&view=rev
Log:
LUCENE-4089: add documentation for termsIndexInterval/Divisor

Modified:
    lucene/dev/branches/branch_4x/   (props changed)
    lucene/dev/branches/branch_4x/lucene/   (props changed)
    lucene/dev/branches/branch_4x/lucene/core/   (props changed)
    lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/index/DirectoryReader.java
    lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/index/LiveIndexWriterConfig.java

Modified: lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/index/DirectoryReader.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/index/DirectoryReader.java?rev=1369023&r1=1369022&r2=1369023&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/index/DirectoryReader.java (original)
+++ lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/index/DirectoryReader.java Fri Aug  3 15:21:02 2012
@@ -75,6 +75,9 @@ public abstract class DirectoryReader ex
    *  memory usage, at the expense of higher latency when
    *  loading a TermInfo.  The default value is 1.  Set this
    *  to -1 to skip loading the terms index entirely.
+   *  <b>NOTE:</b> divisor settings &gt; 1 do not apply to all PostingsFormat
+   *  implementations, including the default one in this release. It only makes
+   *  sense for terms indexes that can efficiently re-sample terms at load time.
    * @throws IOException if there is a low-level IO error
    */
   public static DirectoryReader open(final Directory directory, int termInfosIndexDivisor) throws IOException {
@@ -126,6 +129,9 @@ public abstract class DirectoryReader ex
    *  memory usage, at the expense of higher latency when
    *  loading a TermInfo.  The default value is 1.  Set this
    *  to -1 to skip loading the terms index entirely.
+   *  <b>NOTE:</b> divisor settings &gt; 1 do not apply to all PostingsFormat
+   *  implementations, including the default one in this release. It only makes
+   *  sense for terms indexes that can efficiently re-sample terms at load time.
    * @throws IOException if there is a low-level IO error
    */
   public static DirectoryReader open(final IndexCommit commit, int termInfosIndexDivisor) throws IOException {

Modified: lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/index/LiveIndexWriterConfig.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/index/LiveIndexWriterConfig.java?rev=1369023&r1=1369022&r2=1369023&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/index/LiveIndexWriterConfig.java (original)
+++ lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/index/LiveIndexWriterConfig.java Fri Aug  3 15:21:02 2012
@@ -19,6 +19,7 @@ package org.apache.lucene.index;
 
 import org.apache.lucene.analysis.Analyzer;
 import org.apache.lucene.codecs.Codec;
+import org.apache.lucene.codecs.lucene40.Lucene40PostingsFormat; // javadocs
 import org.apache.lucene.index.DocumentsWriterPerThread.IndexingChain;
 import org.apache.lucene.index.IndexWriter.IndexReaderWarmer;
 import org.apache.lucene.index.IndexWriterConfig.OpenMode;
@@ -146,6 +147,29 @@ public class LiveIndexWriterConfig {
    * Takes effect immediately, but only applies to newly flushed/merged
    * segments.
    * 
+   * <p>
+   * <b>NOTE:</b> This parameter does not apply to all PostingsFormat implementations,
+   * including the default one in this release. It only makes sense for term indexes
+   * that are implemented as a fixed gap between terms. For example, 
+   * {@link Lucene40PostingsFormat} implements the term index instead based upon how
+   * terms share prefixes. To configure its parameters (the minimum and maximum size
+   * for a block), you would instead use  {@link Lucene40PostingsFormat#Lucene40PostingsFormat(int, int)}.
+   * which can also be configured on a per-field basis:
+   * <pre class="prettyprint">
+   * //customize Lucene40PostingsFormat, passing minBlockSize=50, maxBlockSize=100
+   * final PostingsFormat tweakedPostings = new Lucene40PostingsFormat(50, 100);
+   * iwc.setCodec(new Lucene40Codec() {
+   *   &#64;Override
+   *   public PostingsFormat getPostingsFormatForField(String field) {
+   *     if (field.equals("fieldWithTonsOfTerms"))
+   *       return tweakedPostings;
+   *     else
+   *       return super.getPostingsFormatForField(field);
+   *   }
+   * });
+   * </pre>
+   * Note that other implementations may have their own parameters, or no parameters at all.
+   * 
    * @see IndexWriterConfig#DEFAULT_TERM_INDEX_INTERVAL
    */
   public LiveIndexWriterConfig setTermIndexInterval(int interval) { // TODO: this should be private to the codec, not settable here
@@ -335,6 +359,10 @@ public class LiveIndexWriterConfig {
    * <p>
    * Takes effect immediately, but only applies to readers opened after this
    * call
+   * <p>
+   * <b>NOTE:</b> divisor settings &gt; 1 do not apply to all PostingsFormat
+   * implementations, including the default one in this release. It only makes
+   * sense for terms indexes that can efficiently re-sample terms at load time.
    */
   public LiveIndexWriterConfig setReaderTermsIndexDivisor(int divisor) {
     if (divisor <= 0 && divisor != -1) {