docs/attachments/LUCENE-2239/LUCENE-2239.patch

Index: src/java/org/apache/lucene/store/FSDirectory.java
===================================================================
--- src/java/org/apache/lucene/store/FSDirectory.java	(revision 988223)
+++ src/java/org/apache/lucene/store/FSDirectory.java	(working copy)
@@ -31,6 +31,7 @@
 import static java.util.Collections.synchronizedSet;
 import java.util.HashSet;
 import java.util.Set;
+import java.util.concurrent.Future;
 
 import org.apache.lucene.store.SimpleFSDirectory.SimpleFSIndexInput;
 import org.apache.lucene.util.ThreadInterruptedException;
@@ -58,7 +59,12 @@
  *       href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6265734">Sun
  *       JRE bug</a> this is a poor choice for Windows, but
  *       on all other platforms this is the preferred
- *       choice.
+ *       choice. Applications using {@link Thread#interrupt()} or
+ *       {@link Future#cancel(boolean)} should use
+ *       {@link SimpleFSDirectory} instead. See {@link NIOFSDirectory} java doc
+ *       for details.
+ *        
+ *        
  *
  *  <li> {@link MMapDirectory} uses memory-mapped IO when
  *       reading. This is a good choice if you have plenty
@@ -84,6 +90,11 @@
  *       an important limitation to be aware of. This class supplies a
  *       (possibly dangerous) workaround mentioned in the bug report,
  *       which may fail on non-Sun JVMs.
+ *       
+ *       Applications using {@link Thread#interrupt()} or
+ *       {@link Future#cancel(boolean)} should use
+ *       {@link SimpleFSDirectory} instead. See {@link MMapDirectory}
+ *       java doc for details.
  * </ul>
  *
  * Unfortunately, because of system peculiarities, there is
@@ -175,7 +186,9 @@
    *
    *  <p>Currently this returns {@link NIOFSDirectory}
    *  on non-Windows JREs and {@link SimpleFSDirectory}
-   *  on Windows.
+   *  on Windows. It is highly recommended to consult the
+   *  implementations documentation for you platform before
+   *  using this method.
    *
    * <p><b>NOTE</b>: this method may suddenly change which
    * implementation is returned from release to release, in
Index: src/java/org/apache/lucene/store/MMapDirectory.java
===================================================================
--- src/java/org/apache/lucene/store/MMapDirectory.java	(revision 988223)
+++ src/java/org/apache/lucene/store/MMapDirectory.java	(working copy)
@@ -68,6 +68,13 @@
  * an undocumented internal cleanup functionality.
  * {@link #UNMAP_SUPPORTED} is <code>true</code>, if the workaround
  * can be enabled (with no guarantees).
+ * <p>
+ * <b>NOTE:</b> Accessing this class either directly or
+ * indirectly from a thread while it's interrupted can close the
+ * underlying channel immediately if at the same time the thread is
+ * blocked on IO. The channel will remain closed and subsequent access
+ * to {@link MMapDirectory} will throw a {@link ClosedChannelException}. 
+ * </p>
  */
 public class MMapDirectory extends FSDirectory {
   private boolean useUnmapHack = false;
Index: src/java/org/apache/lucene/store/NIOFSDirectory.java
===================================================================
--- src/java/org/apache/lucene/store/NIOFSDirectory.java	(revision 988223)
+++ src/java/org/apache/lucene/store/NIOFSDirectory.java	(working copy)
@@ -21,22 +21,32 @@
 import java.io.IOException;
 import java.nio.ByteBuffer;
 import java.nio.channels.FileChannel;
+import java.util.concurrent.Future; // javadoc
 
 /**
- * An {@link FSDirectory} implementation that uses
- * java.nio's FileChannel's positional read, which allows
- * multiple threads to read from the same file without
- * synchronizing.
- *
- * <p>This class only uses FileChannel when reading; writing
- * is achieved with {@link FSDirectory.FSIndexOutput}.
- * 
- * <p><b>NOTE</b>: NIOFSDirectory is not recommended on Windows because of a bug
- * in how FileChannel.read is implemented in Sun's JRE.
- * Inside of the implementation the position is apparently
- * synchronized.  See <a
+ * An {@link FSDirectory} implementation that uses java.nio's FileChannel's
+ * positional read, which allows multiple threads to read from the same file
+ * without synchronizing.
+ * <p>
+ * This class only uses FileChannel when reading; writing is achieved with
+ * {@link SimpleFSDirectory.SimpleFSIndexOutput}.
+ * <p>
+ * <b>NOTE</b>: NIOFSDirectory is not recommended on Windows because of a bug in
+ * how FileChannel.read is implemented in Sun's JRE. Inside of the
+ * implementation the position is apparently synchronized. See <a
  * href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6265734">here</a>
  * for details.
+ * </p>
+ * <p>
+ * <font color="red"><b>NOTE:</b> Accessing this class either directly or
+ * indirectly from a thread while it's interrupted can close the
+ * underlying file descriptor immediately if at the same time the thread is
+ * blocked on IO. The file descriptor will remain closed and subsequent access
+ * to {@link NIOFSDirectory} will throw a {@link ClosedChannelException}. If
+ * your application uses either {@link Thread#interrupt()} or
+ * {@link Future#cancel(boolean)} you should use {@link SimpleFSDirectory} in
+ * favor of {@link NIOFSDirectory}.</font>
+ * </p>
  */
 public class NIOFSDirectory extends FSDirectory {