[IO-726] Add MemoryMappedInputStream, #215.

Modified PR 215 from shollander with:
- Do not write the console.
- Simplify cleaner check support.
- Simplify exception handling.
- Don't initialize instance variables to their default values.
- Un-nest else clause.
- Declaring interfaces as static is redundant.
- Use EOF constant instead of magic number.
- Don't throw RuntimeException, use IllegalStateException.
- Pacakge private class does not need public method.
- Use final.
- Improve Javadocs.
- Javadoc sentences should end in a period.
- Javadoc do not need first sentence to be in an HTML p element.
- No need to use `this.` when you do not need to.
- In-line some single use variables.
- Sort members.

Author: Gary Gregory

src/changes/changes.xml

@@ -74,6 +74,9 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="fix" due-to="Arturo Bernal">
         Fix Javadoc in ThreadMonitor#run() method. #273.
       </action>
+      <action issue="IO-726" dev="ggregory" type="fix" due-to="shollander, Gary Gregory">
+        Add MemoryMappedInputStream. #215.
+      </action>
       <!-- ADD -->
       <action dev="ggregory" type="add" due-to="Gary Gregory">
         Add BrokenReader.INSTANCE.

src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java

@@ -18,8 +18,6 @@
 import java.io.File;
 import java.io.IOException;
 import java.io.InputStream;
-import java.lang.reflect.Field;
-import java.lang.reflect.Method;
 import java.nio.ByteBuffer;
 import java.nio.channels.FileChannel;
 import java.nio.file.Path;
@@ -40,29 +38,12 @@
  *
  * @since 2.9.0
  */
-@SuppressWarnings("restriction")
 public final class BufferedFileChannelInputStream extends InputStream {
 
     private final ByteBuffer byteBuffer;
 
     private final FileChannel fileChannel;
 
-    private static final Class<?> DIRECT_BUFFER_CLASS = getDirectBufferClass();
-
-    private static Class<?> getDirectBufferClass() {
-        Class<?> res = null;
-        try {
-            res = Class.forName("sun.nio.ch.DirectBuffer");
-        } catch (final IllegalAccessError | ClassNotFoundException ignored) {
-            // ignored
-        }
-        return res;
-    }
-
-    private static boolean isDirectBuffer(final Object object) {
-        return DIRECT_BUFFER_CLASS != null && DIRECT_BUFFER_CLASS.isInstance(object);
-    }
-
     /**
      * Constructs a new instance for the given File.
      *
@@ -115,75 +96,30 @@ public synchronized int available() throws IOException {
 
     /**
      * Attempts to clean up a ByteBuffer if it is direct or memory-mapped. This uses an *unsafe* Sun API that will cause
-     * errors if one attempts to read from the disposed buffer. However, neither the bytes allocated to direct buffers
-     * nor file descriptors opened for memory-mapped buffers put pressure on the garbage collector. Waiting for garbage
+     * errors if one attempts to read from the disposed buffer. However, neither the bytes allocated to direct buffers nor
+     * file descriptors opened for memory-mapped buffers put pressure on the garbage collector. Waiting for garbage
      * collection may lead to the depletion of off-heap memory or huge numbers of open files. There's unfortunately no
      * standard API to manually dispose of these kinds of buffers.
      *
      * @param buffer the buffer to clean.
      */
     private void clean(final ByteBuffer buffer) {
-        if (isDirectBuffer(buffer)) {
+        if (buffer.isDirect()) {
             cleanDirectBuffer(buffer);
         }
     }
 
     /**
-     * In Java 8, the type of DirectBuffer.cleaner() was sun.misc.Cleaner, and it was possible to access the method
-     * sun.misc.Cleaner.clean() to invoke it. The type changed to jdk.internal.ref.Cleaner in later JDKs, and the
-     * .clean() method is not accessible even with reflection. However sun.misc.Unsafe added a invokeCleaner() method in
-     * JDK 9+ and this is still accessible with reflection.
+     * In Java 8, the type of {@code sun.nio.ch.DirectBuffer.cleaner()} was {@code sun.misc.Cleaner}, and it was possible to
+     * access the method {@code sun.misc.Cleaner.clean()} to invoke it. The type changed to {@code jdk.internal.ref.Cleaner}
+     * in later JDKs, and the {@code clean()} method is not accessible even with reflection. However {@code sun.misc.Unsafe}
+     * added an {@code invokeCleaner()} method in JDK 9+ and this is still accessible with reflection.
      *
      * @param buffer the buffer to clean. must be a DirectBuffer.
      */
     private void cleanDirectBuffer(final ByteBuffer buffer) {
-        //
-        // Ported from StorageUtils.scala.
-        //
-//      private val bufferCleaner: DirectBuffer => Unit =
-//      if (SystemUtils.isJavaVersionAtLeast(JavaVersion.JAVA_9)) {
-//        val cleanerMethod =
-//          Utils.classForName("sun.misc.Unsafe").getMethod("invokeCleaner", classOf[ByteBuffer])
-//        val unsafeField = classOf[Unsafe].getDeclaredField("theUnsafe")
-//        unsafeField.setAccessible(true)
-//        val unsafe = unsafeField.get(null).asInstanceOf[Unsafe]
-//        buffer: DirectBuffer => cleanerMethod.invoke(unsafe, buffer)
-//      } else {
-//        val cleanerMethod = Utils.classForName("sun.misc.Cleaner").getMethod("clean")
-//        buffer: DirectBuffer => {
-//          // Careful to avoid the return type of .cleaner(), which changes with JDK
-//          val cleaner: AnyRef = buffer.cleaner()
-//          if (cleaner != null) {
-//            cleanerMethod.invoke(cleaner)
-//          }
-//        }
-//      }
-        //
-        final String specVer = System.getProperty("java.specification.version");
-        if ("1.8".equals(specVer)) {
-            // On Java 8, but also compiles on Java 11.
-            try {
-              final Class<?> clsCleaner = Class.forName("sun.misc.Cleaner");
-              final Method cleanerMethod = DIRECT_BUFFER_CLASS.getMethod("cleaner");
-              final Object cleaner = cleanerMethod.invoke(buffer);
-              if (cleaner != null) {
-                  final Method cleanMethod = clsCleaner.getMethod("clean");
-                  cleanMethod.invoke(cleaner);
-              }
-            } catch (final ReflectiveOperationException e) {
-                throw new IllegalStateException(e);
-            }
-        } else {
-            // On Java 9 and up, but compiles on Java 8.
-            try {
-                final Class<?> clsUnsafe = Class.forName("sun.misc.Unsafe");
-                final Method cleanerMethod = clsUnsafe.getMethod("invokeCleaner", ByteBuffer.class);
-                final Field unsafeField = clsUnsafe.getDeclaredField("theUnsafe");
-                unsafeField.setAccessible(true);
-                cleanerMethod.invoke(unsafeField.get(null), buffer);
-            } catch (final ReflectiveOperationException e) {
-                throw new IllegalStateException(e);
-            }
+        if (ByteBufferCleaner.isSupported()) {
+            ByteBufferCleaner.clean(buffer);
         }
     }
 

src/main/java/org/apache/commons/io/input/ByteBufferCleaner.java

@@ -0,0 +1,116 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.io.input;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.nio.ByteBuffer;
+
+/**
+ * Cleans a direct {@link ByteBuffer}. Without manual intervention, direct ByteBuffers will be cleaned eventually upon
+ * garbage collection. However, this should not be be relied upon since it may not occur in a timely fashion -
+ * especially since off heap ByeBuffers don't put pressure on the garbage collector.
+ * <p>
+ * <b>Warning:</b> Do not attempt to use a direct {@link ByteBuffer} that has been cleaned or bad things will happen.
+ * Don't use this class unless you can ensure that the cleaned buffer will not be accessed anymore.
+ * </p>
+ * <p>
+ * See <a href=https://bugs.openjdk.java.net/browse/JDK-4724038>JDK-4724038</a>
+ * </p>
+ */
+class ByteBufferCleaner {
+
+    private interface Cleaner {
+        void clean(ByteBuffer buffer) throws ReflectiveOperationException;
+    }
+
+    private static class Java8Cleaner implements Cleaner {
+
+        private final Method cleanerMethod;
+        private final Method cleanMethod;
+
+        private Java8Cleaner() throws ReflectiveOperationException, SecurityException {
+            cleanMethod = Class.forName("sun.misc.Cleaner").getMethod("clean");
+            cleanerMethod = Class.forName("sun.nio.ch.DirectBuffer").getMethod("cleaner");
+        }
+
+        @Override
+        public void clean(final ByteBuffer buffer) throws ReflectiveOperationException {
+            final Object cleaner = cleanerMethod.invoke(buffer);
+            if (cleaner != null) {
+                cleanMethod.invoke(cleaner);
+            }
+        }
+    }
+
+    private static class Java9Cleaner implements Cleaner {
+
+        private final Object theUnsafe;
+        private final Method invokeCleaner;
+
+        private Java9Cleaner() throws ReflectiveOperationException, SecurityException {
+            final Class<?> unsafeClass = Class.forName("sun.misc.Unsafe");
+            final Field field = unsafeClass.getDeclaredField("theUnsafe");
+            field.setAccessible(true);
+            theUnsafe = field.get(null);
+            invokeCleaner = unsafeClass.getMethod("invokeCleaner", ByteBuffer.class);
+        }
+
+        @Override
+        public void clean(final ByteBuffer buffer) throws ReflectiveOperationException {
+            invokeCleaner.invoke(theUnsafe, buffer);
+        }
+    }
+
+    private static final Cleaner INSTANCE = getCleaner();
+
+    /**
+     * Releases memory held by the given {@link ByteBuffer}.
+     *
+     * @param buffer to release.
+     * @throws IllegalStateException on internal failure.
+     */
+    static void clean(final ByteBuffer buffer) {
+        try {
+            INSTANCE.clean(buffer);
+        } catch (final Exception e) {
+            throw new IllegalStateException("Failed to clean direct buffer.", e);
+        }
+    }
+
+    private static Cleaner getCleaner() {
+        try {
+            return new Java8Cleaner();
+        } catch (final Exception e) {
+            try {
+                return new Java9Cleaner();
+            } catch (final Exception e1) {
+                throw new IllegalStateException("Failed to initialize a Cleaner.", e);
+            }
+        }
+    }
+
+    /**
+     * Tests if were able to load a suitable cleaner for the current JVM. Attempting to call
+     * {@code ByteBufferCleaner#clean(ByteBuffer)} when this method returns false will result in an exception.
+     *
+     * @return {@code true} if cleaning is supported, {@code false} otherwise.
+     */
+    static boolean isSupported() {
+        return INSTANCE != null;
+    }
+}