From c678de49eeb4b16b3e31f5f2b9ae9cdf5985dc44 Mon Sep 17 00:00:00 2001
From: Uwe Schindler <uschindler@apache.org>
Date: Fri, 13 May 2011 10:47:30 +0000
Subject: [PATCH] LUCENE-3082: Fix javadocs and add Version parameter to ctor

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1102658 13f79535-47bb-0310-9956-ffa450edef68
---
 .../apache/lucene/index/IndexUpgrader.java    | 30 ++++++++++++++-----
 .../lucene/index/UpgradeIndexMergePolicy.java |  5 ++++
 2 files changed, 27 insertions(+), 8 deletions(-)

diff --git a/lucene/src/java/org/apache/lucene/index/IndexUpgrader.java b/lucene/src/java/org/apache/lucene/index/IndexUpgrader.java
index e53dae99a2c..c33d803231d 100644
--- a/lucene/src/java/org/apache/lucene/index/IndexUpgrader.java
+++ b/lucene/src/java/org/apache/lucene/index/IndexUpgrader.java
@@ -40,7 +40,13 @@ import java.util.Collection;
   * refuses to run by default. Specify {@code -delete-prior-commits}
   * to override this, allowing the tool to delete all but the last commit.
   * From Java code this can be enabled by passing {@code true} to
-  * {@link #IndexUpgrader(Directory,PrintStream,boolean)}.
+  * {@link #IndexUpgrader(Directory,Version,PrintStream,boolean)}.
+  * <p><b>Warning:</b> This tool may reorder documents if the index was partially
+  * upgraded before execution (e.g., documents were added). If your application relies
+  * on &quot;monotonicity&quot; of doc IDs (which means that the order in which the documents
+  * were added to the index is preserved), do a full optimize instead.
+  * The {@link MergePolicy} set by {@link IndexWriterConfig} may also reorder
+  * documents.
   */
 public final class IndexUpgrader {
 
@@ -52,9 +58,11 @@ public final class IndexUpgrader {
     System.err.println("reason, if the incoming index has more than one commit, the tool");
     System.err.println("refuses to run by default. Specify -delete-prior-commits to override");
     System.err.println("this, allowing the tool to delete all but the last commit.");
+    System.err.println("WARNING: This tool may reorder document IDs!");
     System.exit(1);
   }
 
+  @SuppressWarnings("deprecation")
   public static void main(String[] args) throws IOException {
     String dir = null;
     boolean deletePriorCommits = false;
@@ -74,7 +82,7 @@ public final class IndexUpgrader {
       printUsage();
     }
     
-    new IndexUpgrader(FSDirectory.open(new File(dir)), out, deletePriorCommits).upgrade();
+    new IndexUpgrader(FSDirectory.open(new File(dir)), Version.LUCENE_CURRENT, out, deletePriorCommits).upgrade();
   }
   
   private final Directory dir;
@@ -82,16 +90,22 @@ public final class IndexUpgrader {
   private final IndexWriterConfig iwc;
   private final boolean deletePriorCommits;
   
-  @SuppressWarnings("deprecation")
-  public IndexUpgrader(Directory dir) {
-    this(dir, new IndexWriterConfig(Version.LUCENE_CURRENT, null), null, false);
+  /** Creates index upgrader on the given directory, using an {@link IndexWriter} using the given
+   * {@code matchVersion}. The tool refuses to upgrade indexes with multiple commit points. */
+  public IndexUpgrader(Directory dir, Version matchVersion) {
+    this(dir, new IndexWriterConfig(matchVersion, null), null, false);
   }
   
-  @SuppressWarnings("deprecation")
-  public IndexUpgrader(Directory dir, PrintStream infoStream, boolean deletePriorCommits) {
-    this(dir, new IndexWriterConfig(Version.LUCENE_CURRENT, null), infoStream, deletePriorCommits);
+  /** Creates index upgrader on the given directory, using an {@link IndexWriter} using the given
+   * {@code matchVersion}. You have the possibility to upgrade indexes with multiple commit points by removing
+   * all older ones. If {@code infoStream} is not {@code null}, all logging output will be sent to this stream. */
+  public IndexUpgrader(Directory dir, Version matchVersion, PrintStream infoStream, boolean deletePriorCommits) {
+    this(dir, new IndexWriterConfig(matchVersion, null), infoStream, deletePriorCommits);
   }
   
+  /** Creates index upgrader on the given directory, using an {@link IndexWriter} using the given
+   * config. You have the possibility to upgrade indexes with multiple commit points by removing
+   * all older ones. If {@code infoStream} is not {@code null}, all logging output will be sent to this stream. */
   public IndexUpgrader(Directory dir, IndexWriterConfig iwc, PrintStream infoStream, boolean deletePriorCommits) {
     this.dir = dir;
     this.iwc = iwc;
diff --git a/lucene/src/java/org/apache/lucene/index/UpgradeIndexMergePolicy.java b/lucene/src/java/org/apache/lucene/index/UpgradeIndexMergePolicy.java
index 7e57888461d..f21e59f2a77 100644
--- a/lucene/src/java/org/apache/lucene/index/UpgradeIndexMergePolicy.java
+++ b/lucene/src/java/org/apache/lucene/index/UpgradeIndexMergePolicy.java
@@ -40,6 +40,11 @@ import java.util.Set;
   *  w.optimize();
   *  w.close();
   * </pre>
+  * <p><b>Warning:</b> This merge policy may reorder documents if the index was partially
+  * upgraded before calling optimize (e.g., documents were added). If your application relies
+  * on &quot;monotonicity&quot; of doc IDs (which means that the order in which the documents
+  * were added to the index is preserved), do a full optimize instead. Please note, the
+  * delegate {@code MergePolicy} may also reorder documents.
   * @lucene.experimental
   * @see IndexUpgrader
   */