src/java.base/share/classes/java/nio/channels/FileChannel.java

rev 54341 : 8221397: Support implementation-defined Map Modes
Summary: Allow implementation-defined extensions to FileChannel MapMode enum
reviewed-by: duke

@@ -30,10 +30,11 @@
 import java.nio.MappedByteBuffer;
 import java.nio.channels.spi.AbstractInterruptibleChannel;
 import java.nio.file.*;
 import java.nio.file.attribute.FileAttribute;
 import java.nio.file.spi.*;
+import java.util.Objects;
 import java.util.Set;
 import java.util.HashSet;
 import java.util.Collections;
 
 /**

@@ -789,11 +790,11 @@
 
 
     // -- Memory-mapped buffers --
 
     /**
-     * A typesafe enumeration for file-mapping modes.
+     * A file-mapping mode.
      *
      * @since 1.4
      *
      * @see java.nio.channels.FileChannel#map
      */

@@ -817,12 +818,17 @@
         public static final MapMode PRIVATE
             = new MapMode("PRIVATE");
 
         private final String name;
 
-        private MapMode(String name) {
-            this.name = name;
+        /**
+         * Constructs an instance of this class.
+         * @param name the name of the map mode
+         * @since 13
+         */
+        public MapMode(String name) {
+            this.name = Objects.requireNonNull(name);
         }
 
         /**
          * Returns a string describing this file-mapping mode.
          *

@@ -835,12 +841,12 @@
     }
 
     /**
      * Maps a region of this channel's file directly into memory.
      *
-     * <p> A region of a file may be mapped into memory in one of three modes:
-     * </p>
+     * <p> The {@code mode} parameter specifies how the region of the file is
+     * mapped and may be one of the following modes:
      *
      * <ul>
      *
      *   <li><p> <i>Read-only:</i> Any attempt to modify the resulting buffer
      *   will cause a {@link java.nio.ReadOnlyBufferException} to be thrown.

@@ -857,10 +863,12 @@
      *   copies of the modified portions of the buffer to be created.  ({@link
      *   MapMode#PRIVATE MapMode.PRIVATE}) </p></li>
      *
      * </ul>
      *
+     * <p> An implementation may support additional map modes.
+     *
      * <p> For a read-only mapping, this channel must have been opened for
      * reading; for a read/write or private mapping, this channel must have
      * been opened for both reading and writing.
      *
      * <p> The {@link MappedByteBuffer <i>mapped byte buffer</i>}

@@ -890,11 +898,12 @@
      * @param  mode
      *         One of the constants {@link MapMode#READ_ONLY READ_ONLY}, {@link
      *         MapMode#READ_WRITE READ_WRITE}, or {@link MapMode#PRIVATE
      *         PRIVATE} defined in the {@link MapMode} class, according to
      *         whether the file is to be mapped read-only, read/write, or
-     *         privately (copy-on-write), respectively
+     *         privately (copy-on-write), respectively, or an implementation
+     *         specific map mode
      *
      * @param  position
      *         The position within the file at which the mapped region
      *         is to start; must be non-negative
      *

@@ -903,29 +912,32 @@
      *         no greater than {@link java.lang.Integer#MAX_VALUE}
      *
      * @return  The mapped byte buffer
      *
      * @throws NonReadableChannelException
-     *         If the {@code mode} is {@link MapMode#READ_ONLY READ_ONLY} but
+     *         If the {@code mode} is {@link MapMode#READ_ONLY READ_ONLY} or
+     *         {@link MapMode#READ_ONLY_SYNC READ_ONLY_SYNC} but
      *         this channel was not opened for reading
      *
      * @throws NonWritableChannelException
-     *         If the {@code mode} is {@link MapMode#READ_WRITE READ_WRITE} or
-     *         {@link MapMode#PRIVATE PRIVATE} but this channel was not opened
-     *         for both reading and writing
+     *         If the {@code mode} is {@link MapMode#READ_WRITE READ_WRITE},
+     *         {@link MapMode#PRIVATE PRIVATE} or {@link MapMode#READ_WRITE_SYNC READ_WRITE_SYNC}
+     *         but this channel was not opened for both reading and writing
      *
      * @throws IllegalArgumentException
      *         If the preconditions on the parameters do not hold
      *
+     * @throws UnsupportedOperationException
+     *         If an unsupported map mode is specified
+     *
      * @throws IOException
      *         If some other I/O error occurs
      *
      * @see java.nio.channels.FileChannel.MapMode
      * @see java.nio.MappedByteBuffer
      */
-    public abstract MappedByteBuffer map(MapMode mode,
-                                         long position, long size)
+    public abstract MappedByteBuffer map(MapMode mode, long position, long size)
         throws IOException;
 
 
     // -- Locks --