mirror of https://github.com/apache/lucene.git
LUCENE-3866: Add some JavaDocs to prevent modification of the array containing the sequential subreaders. This is a trap! We should maybe change getSequentialSubReaders and similar methods in IndexReaderContext to return List<R extends IndexReader>. I will open issue for discussion.
git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1300016 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
parent
9e8ea09d7a
commit
b83d177b7f
|
@ -53,6 +53,14 @@ public abstract class BaseCompositeReader<R extends IndexReader> extends Composi
|
|||
private final int numDocs;
|
||||
private final boolean hasDeletions;
|
||||
|
||||
/**
|
||||
* Constructs a {@code BaseCompositeReader} on the given subReaders.
|
||||
* @param subReaders the wrapped sub-readers. This array is returned by
|
||||
* {@link #getSequentialSubReaders} and used to resolve the correct
|
||||
* subreader for docID-based methods. <b>Please note:</b> This array is <b>not</b>
|
||||
* cloned and not protected for modification, the subclass is responsible
|
||||
* to do this.
|
||||
*/
|
||||
protected BaseCompositeReader(R[] subReaders) throws IOException {
|
||||
this.subReaders = subReaders;
|
||||
starts = new int[subReaders.length + 1]; // build starts array
|
||||
|
|
|
@ -81,6 +81,9 @@ public abstract class CompositeReader extends IndexReader {
|
|||
* If this method returns an empty array, that means this
|
||||
* reader is a null reader (for example a MultiReader
|
||||
* that has no sub readers).
|
||||
* <p><b>Warning:</b> Don't modify the returned array!
|
||||
* Doing so will corrupt the internal structure of this
|
||||
* {@code CompositeReader}.
|
||||
*/
|
||||
public abstract IndexReader[] getSequentialSubReaders();
|
||||
|
||||
|
|
|
@ -323,8 +323,17 @@ public abstract class DirectoryReader extends BaseCompositeReader<AtomicReader>
|
|||
}
|
||||
}
|
||||
|
||||
protected DirectoryReader(Directory directory, AtomicReader[] readers) throws CorruptIndexException, IOException {
|
||||
super(readers);
|
||||
/**
|
||||
* Expert: Constructs a {@code DirectoryReader} on the given subReaders.
|
||||
* @param segmentReaders the wrapped atomic index segment readers. This array is
|
||||
* returned by {@link #getSequentialSubReaders} and used to resolve the correct
|
||||
* subreader for docID-based methods. <b>Please note:</b> This array is <b>not</b>
|
||||
* cloned and not protected for modification outside of this reader.
|
||||
* Subclasses of {@code DirectoryReader} should take care to not allow
|
||||
* modification of this internal array, e.g. {@link #doOpenIfChanged()}.
|
||||
*/
|
||||
protected DirectoryReader(Directory directory, AtomicReader[] segmentReaders) throws CorruptIndexException, IOException {
|
||||
super(segmentReaders);
|
||||
this.directory = directory;
|
||||
}
|
||||
|
||||
|
|
|
@ -41,25 +41,27 @@ public abstract class IndexReaderContext {
|
|||
this.isTopLevel = parent==null;
|
||||
}
|
||||
|
||||
/** Returns the {@link IndexReader}, this context represents. */
|
||||
public abstract IndexReader reader();
|
||||
|
||||
/**
|
||||
* Returns the context's leaves if this context is a top-level context
|
||||
* otherwise <code>null</code>. For convenience, if this is an
|
||||
* {@link AtomicReaderContext} this returns itsself as the only leaf.
|
||||
* <p>
|
||||
* Note: this is convenience method since leaves can always be obtained by
|
||||
* <p>Note: this is convenience method since leaves can always be obtained by
|
||||
* walking the context tree.
|
||||
* <p><b>Warning:</b> Don't modify the returned array!
|
||||
* Doing so will corrupt the internal structure of this
|
||||
* {@code IndexReaderContext}.
|
||||
*/
|
||||
public abstract AtomicReaderContext[] leaves();
|
||||
|
||||
/**
|
||||
* Returns the context's children iff this context is a composite context
|
||||
* otherwise <code>null</code>.
|
||||
* <p>
|
||||
* Note: this method is a convenience method to prevent
|
||||
* <code>instanceof</code> checks and type-casts to
|
||||
* {@link CompositeReaderContext}.
|
||||
* <p><b>Warning:</b> Don't modify the returned array!
|
||||
* Doing so will corrupt the internal structure of this
|
||||
* {@code IndexReaderContext}.
|
||||
*/
|
||||
public abstract IndexReaderContext[] children();
|
||||
}
|
|
@ -51,7 +51,7 @@ public class MultiReader extends BaseCompositeReader<IndexReader> {
|
|||
|
||||
/**
|
||||
* <p>Construct a MultiReader aggregating the named set of (sub)readers.
|
||||
* @param subReaders set of (sub)readers
|
||||
* @param subReaders set of (sub)readers; this array will be cloned.
|
||||
* @param closeSubReaders indicates whether the subreaders should be closed
|
||||
* when this MultiReader is closed
|
||||
*/
|
||||
|
|
Loading…
Reference in New Issue