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

lucene/core/src/java/org/apache/lucene/index/BaseCompositeReader.java

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

lucene/core/src/java/org/apache/lucene/index/CompositeReader.java

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

lucene/core/src/java/org/apache/lucene/index/DirectoryReader.java

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

lucene/core/src/java/org/apache/lucene/index/IndexReaderContext.java

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

lucene/core/src/java/org/apache/lucene/index/MultiReader.java

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