LUCENE-1657: make readOnly a required param when opening IndexReader/Searcher

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

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

@@ -34,7 +34,8 @@ import java.util.Map;
  so that any subclass which implements it is searchable.
 
  <p> Concrete subclasses of IndexReader are usually constructed with a call to
- one of the static <code>open()</code> methods, e.g. {@link #open(String)}.
+ one of the static <code>open()</code> methods, e.g. {@link
+ #open(String, boolean)}.
 
  <p> For efficiency, in this API documents are often referred to via
  <i>document numbers</i>, non-negative integers which each name a unique
@@ -70,9 +71,6 @@ import java.util.Map;
 */
 public abstract class IndexReader implements Cloneable {
 
-  // NOTE: in 3.0 this will change to true
-  final static boolean READ_ONLY_DEFAULT = false;
-
   /**
    * Constants describing field properties, for example used for
    * {@link IndexReader#getFieldNames(FieldOption)}.
@@ -203,36 +201,70 @@ public abstract class IndexReader implements Cloneable {
   }
 
   /** Returns a read/write IndexReader reading the index in an FSDirectory in the named
-   path.  <b>NOTE</b>: starting in 3.0 this will return a readOnly IndexReader.
+   *  path.
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
+   * @deprecated Use {@link #open(String, boolean)} instead
    * @param path the path to the index directory */
   public static IndexReader open(String path) throws CorruptIndexException, IOException {
-    return open(FSDirectory.getDirectory(path), true, null, null, READ_ONLY_DEFAULT);
+    return open(FSDirectory.getDirectory(path), true, null, null, false);
+  }
+
+  /** Returns an IndexReader reading the index in an
+   *  FSDirectory in the named path.  You should pass
+   *  readOnly=true, since it gives much better concurrent
+   *  performance, unless you intend to do write operations
+   *  (delete documents or change norms) with the reader.
+   * @throws CorruptIndexException if the index is corrupt
+   * @throws IOException if there is a low-level IO error
+   * @param path the path to the index directory
+   * @param readOnly true if this should be a readOnly
+   * reader */
+  public static IndexReader open(String path, boolean readOnly) throws CorruptIndexException, IOException {
+    return open(FSDirectory.getDirectory(path), true, null, null, readOnly);
   }
 
   /** Returns a read/write IndexReader reading the index in an FSDirectory in the named
-   * path.  <b>NOTE</b>: starting in 3.0 this will return a readOnly IndexReader.
+   *  path.
    * @param path the path to the index directory
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
+   * @deprecated Use {@link #open(File, boolean)} instead
    */
   public static IndexReader open(File path) throws CorruptIndexException, IOException {
-    return open(FSDirectory.getDirectory(path), true, null, null, READ_ONLY_DEFAULT);
+    return open(FSDirectory.getDirectory(path), true, null, null, false);
+  }
+
+  /** Returns an IndexReader reading the index in an
+   *  FSDirectory in the named path.  You should pass
+   *  readOnly=true, since it gives much better concurrent
+   *  performance, unless you intend to do write operations
+   *  (delete documents or change norms) with the reader.
+   * @throws CorruptIndexException if the index is corrupt
+   * @throws IOException if there is a low-level IO error
+   * @param path the path to the index directory
+   * @param readOnly true if this should be a readOnly
+   * reader */
+  public static IndexReader open(File path, boolean readOnly) throws CorruptIndexException, IOException {
+    return open(FSDirectory.getDirectory(path), true, null, null, readOnly);
   }
 
   /** Returns a read/write IndexReader reading the index in
-   * the given Directory. <b>NOTE</b>: starting in 3.0 this
+   *  the given Directory.
-   * will return a readOnly IndexReader.
    * @param directory the index directory
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
+   * @deprecated Use {@link #open(Directory, boolean)} instead
    */
   public static IndexReader open(final Directory directory) throws CorruptIndexException, IOException {
-    return open(directory, false, null, null, READ_ONLY_DEFAULT);
+    return open(directory, false, null, null, false);
   }
 
-  /** Returns a read/write or read only IndexReader reading the index in the given Directory.
+  /** Returns an IndexReader reading the index in the given
+   *  Directory.  You should pass readOnly=true, since it
+   *  gives much better concurrent performance, unless you
+   *  intend to do write operations (delete documents or
+   *  change norms) with the reader.
    * @param directory the index directory
    * @param readOnly true if no changes (deletions, norms) will be made with this IndexReader
    * @throws CorruptIndexException if the index is corrupt
@@ -243,35 +275,51 @@ public abstract class IndexReader implements Cloneable {
   }
 
   /** Expert: returns a read/write IndexReader reading the index in the given
-   * {@link IndexCommit}.  <b>NOTE</b>: starting in 3.0 this
+   * {@link IndexCommit}.
-   * will return a readOnly IndexReader.
    * @param commit the commit point to open
    * @throws CorruptIndexException if the index is corrupt
+   * @deprecated Use {@link #open(IndexCommit, boolean)} instead
    * @throws IOException if there is a low-level IO error
    */
   public static IndexReader open(final IndexCommit commit) throws CorruptIndexException, IOException {
-    return open(commit.getDirectory(), false, null, commit, READ_ONLY_DEFAULT);
+    return open(commit.getDirectory(), false, null, commit, false);
+  }
+
+  /** Expert: returns an IndexReader reading the index in the given
+   *  {@link IndexCommit}.  You should pass readOnly=true, since it
+   *  gives much better concurrent performance, unless you
+   *  intend to do write operations (delete documents or
+   *  change norms) with the reader.
+   * @param commit the commit point to open
+   * @param readOnly true if no changes (deletions, norms) will be made with this IndexReader
+   * @throws CorruptIndexException if the index is corrupt
+   * @throws IOException if there is a low-level IO error
+   */
+  public static IndexReader open(final IndexCommit commit, boolean readOnly) throws CorruptIndexException, IOException {
+    return open(commit.getDirectory(), false, null, commit, readOnly);
   }
 
   /** Expert: returns a read/write IndexReader reading the index in the given
    *  Directory, with a custom {@link IndexDeletionPolicy}.
-   * <b>NOTE</b>: starting in 3.0 this will return a
-   * readOnly IndexReader.
    * @param directory the index directory
    * @param deletionPolicy a custom deletion policy (only used
    *  if you use this reader to perform deletes or to set
    *  norms); see {@link IndexWriter} for details.
+   * @deprecated Use {@link #open(Directory,
+   * IndexDeletionPolicy, boolean)} instead
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
    */
   public static IndexReader open(final Directory directory, IndexDeletionPolicy deletionPolicy) throws CorruptIndexException, IOException {
-    return open(directory, false, deletionPolicy, null, READ_ONLY_DEFAULT);
+    return open(directory, false, deletionPolicy, null, false);
   }
 
-  /** Expert: returns a read/write or read only IndexReader reading the index in the given
+  /** Expert: returns an IndexReader reading the index in
-   * Directory, with a custom {@link IndexDeletionPolicy}.
+   *  the given Directory, with a custom {@link
-   * <b>NOTE</b>: starting in 3.0 this will return a
+   *  IndexDeletionPolicy}.  You should pass readOnly=true,
-   * readOnly IndexReader.
+   *  since it gives much better concurrent performance,
+   *  unless you intend to do write operations (delete
+   *  documents or change norms) with the reader.
    * @param directory the index directory
    * @param deletionPolicy a custom deletion policy (only used
    *  if you use this reader to perform deletes or to set
@@ -286,23 +334,28 @@ public abstract class IndexReader implements Cloneable {
 
   /** Expert: returns a read/write IndexReader reading the index in the given
    * Directory, using a specific commit and with a custom
-   * {@link IndexDeletionPolicy}.  <b>NOTE</b>: starting in
+   * {@link IndexDeletionPolicy}.
-   * 3.0 this will return a readOnly IndexReader.
    * @param commit the specific {@link IndexCommit} to open;
    * see {@link IndexReader#listCommits} to list all commits
    * in a directory
    * @param deletionPolicy a custom deletion policy (only used
    *  if you use this reader to perform deletes or to set
    *  norms); see {@link IndexWriter} for details.
+   * @deprecated Use {@link #open(IndexCommit,
+   * IndexDeletionPolicy, boolean)} instead
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
    */
   public static IndexReader open(final IndexCommit commit, IndexDeletionPolicy deletionPolicy) throws CorruptIndexException, IOException {
-    return open(commit.getDirectory(), false, deletionPolicy, commit, READ_ONLY_DEFAULT);
+    return open(commit.getDirectory(), false, deletionPolicy, commit, false);
   }
 
-  /** Expert: returns a read/write or read only IndexReader reading the index in the given
+  /** Expert: returns an IndexReader reading the index in
-   * Directory, using a specific commit and with a custom {@link IndexDeletionPolicy}.
+   *  the given Directory, using a specific commit and with
+   *  a custom {@link IndexDeletionPolicy}.  You should pass
+   *  readOnly=true, since it gives much better concurrent
+   *  performance, unless you intend to do write operations
+   *  (delete documents or change norms) with the reader.
    * @param commit the specific {@link IndexCommit} to open;
    * see {@link IndexReader#listCommits} to list all commits
    * in a directory

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

@@ -375,9 +375,10 @@ class SegmentReader extends DirectoryIndexReader {
   /**
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
+   * @deprecated
    */
   public static SegmentReader get(SegmentInfo si) throws CorruptIndexException, IOException {
-    return get(READ_ONLY_DEFAULT, si.dir, si, null, false, false, BufferedIndexInput.BUFFER_SIZE, true);
+    return get(false, si.dir, si, null, false, false, BufferedIndexInput.BUFFER_SIZE, true);
   }
 
   /**
@@ -391,25 +392,28 @@ class SegmentReader extends DirectoryIndexReader {
   /**
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
+   * @deprecated
    */
   static SegmentReader get(SegmentInfo si, boolean doOpenStores) throws CorruptIndexException, IOException {
-    return get(READ_ONLY_DEFAULT, si.dir, si, null, false, false, BufferedIndexInput.BUFFER_SIZE, doOpenStores);
+    return get(false, si.dir, si, null, false, false, BufferedIndexInput.BUFFER_SIZE, doOpenStores);
   }
 
   /**
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
+   * @deprecated
    */
   public static SegmentReader get(SegmentInfo si, int readBufferSize) throws CorruptIndexException, IOException {
-    return get(READ_ONLY_DEFAULT, si.dir, si, null, false, false, readBufferSize, true);
+    return get(false, si.dir, si, null, false, false, readBufferSize, true);
   }
 
   /**
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
+   * @deprecated
    */
   static SegmentReader get(SegmentInfo si, int readBufferSize, boolean doOpenStores) throws CorruptIndexException, IOException {
-    return get(READ_ONLY_DEFAULT, si.dir, si, null, false, false, readBufferSize, doOpenStores);
+    return get(false, si.dir, si, null, false, false, readBufferSize, doOpenStores);
   }
 
   /**
@@ -432,13 +436,14 @@ class SegmentReader extends DirectoryIndexReader {
   /**
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
+   * @deprecated
    */
   public static SegmentReader get(Directory dir, SegmentInfo si,
                                   SegmentInfos sis,
                                   boolean closeDir, boolean ownDir,
                                   int readBufferSize)
     throws CorruptIndexException, IOException {
-    return get(READ_ONLY_DEFAULT, dir, si, sis, closeDir, ownDir, readBufferSize, true);
+    return get(false, dir, si, sis, closeDir, ownDir, readBufferSize, true);
   }
 
   /**

src/java/org/apache/lucene/search/IndexSearcher.java

@@ -46,19 +46,51 @@ public class IndexSearcher extends Searcher {
   /** Creates a searcher searching the index in the named directory.
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
+   * @deprecated Use {@link #IndexSearcher(String, boolean)} instead
    */
   public IndexSearcher(String path) throws CorruptIndexException, IOException {
     this(IndexReader.open(path), true);
   }
 
-  /** Creates a searcher searching the index in the provided directory.
+  /** Creates a searcher searching the index in the named
+   *  directory.  You should pass readOnly=true, since it
+   *  gives much better concurrent performance, unless you
+   *  intend to do write operations (delete documents or
+   *  change norms) with the underlying IndexReader.
+   * @param path directory where IndexReader will be opened
+   * @param readOnly if true, the underlying IndexReader
+   * will be opened readOnly
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
    */
+  public IndexSearcher(String path, boolean readOnly) throws CorruptIndexException, IOException {
+    this(IndexReader.open(path, readOnly), true);
+  }
+
+  /** Creates a searcher searching the index in the provided directory.
+   * @throws CorruptIndexException if the index is corrupt
+   * @throws IOException if there is a low-level IO error
+   * @deprecated Use {@link #IndexSearcher(Directory, boolean)} instead
+   */
   public IndexSearcher(Directory directory) throws CorruptIndexException, IOException {
     this(IndexReader.open(directory), true);
   }
 
+  /** Creates a searcher searching the index in the named
+   *  directory.  You should pass readOnly=true, since it
+   *  gives much better concurrent performance, unless you
+   *  intend to do write operations (delete documents or
+   *  change norms) with the underlying IndexReader.
+   * @throws CorruptIndexException if the index is corrupt
+   * @throws IOException if there is a low-level IO error
+   * @param path directory where IndexReader will be opened
+   * @param readOnly if true, the underlying IndexReader
+   * will be opened readOnly
+   */
+  public IndexSearcher(Directory path, boolean readOnly) throws CorruptIndexException, IOException {
+    this(IndexReader.open(path, readOnly), true);
+  }
+
   /** Creates a searcher searching the provided index. */
   public IndexSearcher(IndexReader r) {
     this(r, false);