svn commit: r557553 - in /lucene/java/trunk: CHANGES.txt src/java/org/apache/lucene/document/Field.java

[mi...@apache.org]

Author: mikemccand
Date: Thu Jul 19 03:16:30 2007
New Revision: 557553

URL: http://svn.apache.org/viewvc?view=rev&rev=557553
Log:
LUCENE-963: added caveats to javadocs for new Field setValue(...) methods

Modified:
    lucene/java/trunk/CHANGES.txt
    lucene/java/trunk/src/java/org/apache/lucene/document/Field.java

Modified: lucene/java/trunk/CHANGES.txt
URL: http://svn.apache.org/viewvc/lucene/java/trunk/CHANGES.txt?view=diff&rev=557553&r1=557552&r2=557553
==============================================================================
--- lucene/java/trunk/CHANGES.txt (original)
+++ lucene/java/trunk/CHANGES.txt Thu Jul 19 03:16:30 2007
@@ -18,6 +18,10 @@
  2. LUCENE-944: Remove deprecated methods setUseScorer14() and
     getUseScorer14() from BooleanQuery. (Paul Elschot via Michael Busch)
  
+ 5. LUCENE-963: Add setters to Field to allow for re-using a single
+    Field instance during indexing.  This is a sizable performance
+    gain, especially for small documents.  (Mike McCandless)
+
 Bug fixes
 
  1. LUCENE-933: QueryParser fixed to not produce empty sub 

Modified: lucene/java/trunk/src/java/org/apache/lucene/document/Field.java
URL: http://svn.apache.org/viewvc/lucene/java/trunk/src/java/org/apache/lucene/document/Field.java?view=diff&rev=557553&r1=557552&r2=557553
==============================================================================
--- lucene/java/trunk/src/java/org/apache/lucene/document/Field.java (original)
+++ lucene/java/trunk/src/java/org/apache/lucene/document/Field.java Thu Jul 19 03:16:30 2007
@@ -156,30 +156,35 @@
   public TokenStream tokenStreamValue()   { return fieldsData instanceof TokenStream ? (TokenStream)fieldsData : null; }
   
 
-  /** Expert: change the value of this field.  This can be
-   *  used during indexing to re-use a single Field instance
-   *  to improve indexing speed. */
+  /** <p>Expert: change the value of this field.  This can
+   *  be used during indexing to re-use a single Field
+   *  instance to improve indexing speed by avoiding GC cost
+   *  of new'ing and reclaiming Field instances.  Typically
+   *  a single {@link Document} instance is re-used as
+   *  well.  This helps most on small documents.</p>
+   * 
+   *  <p>Note that you should only use this method after the
+   *  Field has been consumed (ie, the {@link Document}
+   *  containing this Field has been added to the index).
+   *  Also, each Field instance should only be used once
+   *  within a single {@link Document} instance.  See <a
+   *  href="http://wiki.apache.org/lucene-java/ImproveIndexingSpeed">ImproveIndexingSpeed</a>
+   *  for details.</p> */
   public void setValue(String value) {
     fieldsData = value;
   }
 
-  /** Expert: change the value of this field.  This can be
-   *  used during indexing to re-use a single Field instance
-   *  to improve indexing speed. */
+  /** Expert: change the value of this field.  See <a href="#setValue(java.lang.String)">setValue(String)</a>. */
   public void setValue(Reader value) {
     fieldsData = value;
   }
 
-  /** Expert: change the value of this field.  This can be
-   *  used during indexing to re-use a single Field instance
-   *  to improve indexing speed. */
+  /** Expert: change the value of this field.  See <a href="#setValue(java.lang.String)">setValue(String)</a>. */
   public void setValue(byte[] value) {
     fieldsData = value;
   }
 
-  /** Expert: change the value of this field.  This can be
-   *  used during indexing to re-use a single Field instance
-   *  to improve indexing speed. */
+  /** Expert: change the value of this field.  See <a href="#setValue(java.lang.String)">setValue(String)</a>. */
   public void setValue(TokenStream value) {
     fieldsData = value;
   }