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:
Uwe Schindler 2012-03-13 09:05:46 +00:00
parent 9e8ea09d7a
commit b83d177b7f
5 changed files with 31 additions and 9 deletions

View File

@ -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

View File

@ -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();

View File

@ -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;
}

View File

@ -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();
}

View File

@ -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
*/