Concrete subclasses of IndexReader are usually constructed with a call to
- one of the static open() methods, e.g. {@link #open(String)}.
+ one of the static open() methods, e.g. {@link
+ #open(String, boolean)}.
For efficiency, in this API documents are often referred to via document numbers, 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. NOTE: 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. NOTE: 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. NOTE: starting in 3.0 this - * will return a readOnly IndexReader. + * the given Directory. * @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}. NOTE: starting in 3.0 this - * will return a readOnly IndexReader. + * {@link IndexCommit}. * @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}. - * NOTE: starting in 3.0 this will return a - * readOnly IndexReader. + * Directory, with a custom {@link IndexDeletionPolicy}. * @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 - * Directory, with a custom {@link IndexDeletionPolicy}. - * NOTE: starting in 3.0 this will return a - * readOnly IndexReader. + /** Expert: returns an IndexReader reading the index in + * the given Directory, 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 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}. NOTE: starting in - * 3.0 this will return a readOnly IndexReader. + * {@link IndexDeletionPolicy}. * @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 - * Directory, using a specific commit and with a custom {@link IndexDeletionPolicy}. + /** Expert: returns an IndexReader reading the index in + * 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 diff --git a/src/java/org/apache/lucene/index/SegmentReader.java b/src/java/org/apache/lucene/index/SegmentReader.java index 4c354431dff..3d3c7037082 100644 --- a/src/java/org/apache/lucene/index/SegmentReader.java +++ b/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); } /** diff --git a/src/java/org/apache/lucene/search/IndexSearcher.java b/src/java/org/apache/lucene/search/IndexSearcher.java index 0f6c7a8e9d5..b48c1de5568 100644 --- a/src/java/org/apache/lucene/search/IndexSearcher.java +++ b/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);