LUCENE-1546: add IndexReader.flush(String commitUserData)

git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@748493 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -51,6 +51,11 @@ API Changes
    that's visited.  All core collectors now use this API.  (Mark
    Miller, Mike McCandless)
 
+8. LUCENE-1546: Add IndexReader.flush(String commitUserData), allowing
+   you to record an opaque commitUserData into the commit written by
+   IndexReader.  This matches IndexWriter's commit methods.  (Jason
+   Rutherglen via Mike McCandless)
+
 Bug fixes
 
 1. LUCENE-1415: MultiPhraseQuery has incorrect hashCode() and equals()

src/java/org/apache/lucene/index/DirectoryIndexReader.java

@@ -327,6 +327,10 @@ abstract class DirectoryIndexReader extends IndexReader implements Cloneable {
       directory.close();
   }
   
+  protected void doCommit() throws IOException {
+    doCommit(null);
+  }
+
   /**
    * Commit changes resulting from delete, undeleteAll, or
    * setNorm operations
@@ -336,10 +340,10 @@ abstract class DirectoryIndexReader extends IndexReader implements Cloneable {
    * (transactional semantics).
    * @throws IOException if there is a low-level IO error
    */
-  protected void doCommit() throws IOException {
+  protected void doCommit(String commitUserData) throws IOException {
     if (hasChanges) {
       if (segmentInfos != null) {
-
+        segmentInfos.setUserData(commitUserData);
         // Default deleter (for backwards compatibility) is
         // KeepOnlyLastCommitDeleter:
         IndexFileDeleter deleter =  new IndexFileDeleter(directory,

src/java/org/apache/lucene/index/FilterIndexReader.java

@@ -209,7 +209,8 @@ public class FilterIndexReader extends IndexReader {
   }
 
   protected void doDelete(int n) throws  CorruptIndexException, IOException { in.deleteDocument(n); }
-  protected void doCommit() throws IOException { in.commit(); }
+  protected void doCommit() throws IOException { doCommit(null); }
+  protected void doCommit(String commitUserData) throws IOException { in.commit(commitUserData); }
   protected void doClose() throws IOException { in.close(); }
 
 

src/java/org/apache/lucene/index/IndexReader.java

@@ -994,6 +994,17 @@ public abstract class IndexReader implements Cloneable {
     commit();
   }
 
+  /**
+   * @param commitUserData Opaque String that's recorded
+   *  into the segments file in the index, and retrievable
+   *  by {@link IndexReader#getCommitUserData}.
+   * @throws IOException
+   */
+  public final synchronized void flush(String commitUserData) throws IOException {
+    ensureOpen();
+    commit(commitUserData);
+  }
+  
   /**
    * Commit changes resulting from delete, undeleteAll, or
    * setNorm operations
@@ -1004,15 +1015,38 @@ public abstract class IndexReader implements Cloneable {
    * @throws IOException if there is a low-level IO error
    */
   protected final synchronized void commit() throws IOException {
-    if(hasChanges){
-      doCommit();
+    commit(null);
+  }
+  
+  /**
+   * Commit changes resulting from delete, undeleteAll, or
+   * setNorm operations
+   *
+   * If an exception is hit, then either no changes or all
+   * changes will have been committed to the index
+   * (transactional semantics).
+   * @throws IOException if there is a low-level IO error
+   */
+  protected final synchronized void commit(String commitUserData) throws IOException {
+    if (hasChanges) {
+      doCommit(commitUserData);
     }
     hasChanges = false;
   }
 
-  /** Implements commit. */
+  /** Implements commit.
+   *  @deprecated Please implement {@link #doCommit(String)
+   *  instead}. */
   protected abstract void doCommit() throws IOException;
 
+  /** Implements commit.  NOTE: subclasses should override
+   *  this.  In 3.0 this will become an abstract method. */
+  void doCommit(String commitUserData) throws IOException {
+    // Default impl discards commitUserData; all Lucene
+    // subclasses override this (do not discard it).
+    doCommit();
+  }
+
   /**
    * Closes files associated with this index.
    * Also saves any new deletions to disk.

src/java/org/apache/lucene/index/MultiReader.java

@@ -349,8 +349,12 @@ public class MultiReader extends IndexReader implements Cloneable {
   }
 
   protected void doCommit() throws IOException {
+    doCommit(null);
+  }
+  
+  protected void doCommit(String commitUserData) throws IOException {
     for (int i = 0; i < subReaders.length; i++)
-      subReaders[i].commit();
+      subReaders[i].commit(commitUserData);
   }
 
   protected synchronized void doClose() throws IOException {

src/java/org/apache/lucene/index/ParallelReader.java

@@ -437,8 +437,12 @@ public class ParallelReader extends IndexReader {
   }
 
   protected void doCommit() throws IOException {
+    doCommit(null);
+  }
+
+  protected void doCommit(String commitUserData) throws IOException {
     for (int i = 0; i < readers.size(); i++)
-      ((IndexReader)readers.get(i)).commit();
+      ((IndexReader)readers.get(i)).commit(commitUserData);
   }
 
   protected synchronized void doClose() throws IOException {

src/test/org/apache/lucene/index/TestIndexReader.java

@@ -68,7 +68,57 @@ public class TestIndexReader extends LuceneTestCase
     public TestIndexReader(String name) {
         super(name);
     }
+    
+    public void testCommitUserData() throws Exception {
+      RAMDirectory d = new MockRAMDirectory();
+      
+      String cmpCommitUserData = "foo fighters";
+      
+      // set up writer
+      IndexWriter writer = new IndexWriter(d, new StandardAnalyzer(), true, IndexWriter.MaxFieldLength.LIMITED);
+      writer.setMaxBufferedDocs(2);
+      for(int i=0;i<27;i++)
+        addDocumentWithFields(writer);
+      writer.close();
+      
+      IndexReader r = IndexReader.open(d);
+      r.deleteDocument(5);
+      r.flush(cmpCommitUserData);
+      r.close();
+      
+      SegmentInfos sis = new SegmentInfos();
+      sis.read(d);
+      IndexReader r2 = IndexReader.open(d);
+      IndexCommit c = r.getIndexCommit();
+      assertEquals(c.getUserData(), cmpCommitUserData);
 
+      assertEquals(sis.getCurrentSegmentFileName(), c.getSegmentsFileName());
+
+      assertTrue(c.equals(r.getIndexCommit()));
+
+      // Change the index
+      writer = new IndexWriter(d, new StandardAnalyzer(), false, IndexWriter.MaxFieldLength.LIMITED);
+      writer.setMaxBufferedDocs(2);
+      for(int i=0;i<7;i++)
+        addDocumentWithFields(writer);
+      writer.close();
+
+      IndexReader r3 = r2.reopen();
+      assertFalse(c.equals(r3.getIndexCommit()));
+      assertFalse(r2.getIndexCommit().isOptimized());
+      r3.close();
+
+      writer = new IndexWriter(d, new StandardAnalyzer(), false, IndexWriter.MaxFieldLength.LIMITED);
+      writer.optimize();
+      writer.close();
+
+      r3 = r2.reopen();
+      assertTrue(r3.getIndexCommit().isOptimized());
+      r2.close();
+      r3.close();
+      d.close();
+    }
+    
     public void testIsCurrent() throws Exception
     {
       RAMDirectory d = new MockRAMDirectory();