8221397: Support implementation-defined Map Modes
authoradinn
Tue, 09 Apr 2019 16:21:20 +0100
changeset 54532 e9c62d960d64
parent 54531 edf1b4c6b936
child 54533 9219624244a6
child 57329 8009cf5b833d
8221397: Support implementation-defined Map Modes Summary: Allow implementation-defined extensions to FileChannel MapMode enum Reviewed-by: alanb
src/java.base/share/classes/java/nio/channels/FileChannel.java
src/java.base/share/classes/sun/nio/ch/FileChannelImpl.java
--- a/src/java.base/share/classes/java/nio/channels/FileChannel.java	Mon Apr 15 15:38:47 2019 +0200
+++ b/src/java.base/share/classes/java/nio/channels/FileChannel.java	Tue Apr 09 16:21:20 2019 +0100
@@ -791,7 +791,7 @@
     // -- Memory-mapped buffers --
 
     /**
-     * A typesafe enumeration for file-mapping modes.
+     * A file-mapping mode.
      *
      * @since 1.4
      *
@@ -819,6 +819,12 @@
 
         private final String name;
 
+        /**
+         * Constructs an instance of this class. This constructor may be used
+         * by code in java.base to create file mapping modes beyond the file
+         * mapping modes defined here.
+         * @param name the name of the map mode
+         */
         private MapMode(String name) {
             this.name = name;
         }
@@ -837,8 +843,8 @@
     /**
      * 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>
      *
@@ -859,6 +865,8 @@
      *
      * </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.
@@ -892,7 +900,8 @@
      *         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
@@ -905,25 +914,29 @@
      * @return  The mapped byte buffer
      *
      * @throws NonReadableChannelException
-     *         If the {@code mode} is {@link MapMode#READ_ONLY READ_ONLY} but
-     *         this channel was not opened for reading
+     *         If the {@code mode} is {@link MapMode#READ_ONLY READ_ONLY} or
+     *         an implementation specific map mode requiring read access
+     *         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 an implementation specific
+     *         map mode requiring write access 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;
 
 
--- a/src/java.base/share/classes/sun/nio/ch/FileChannelImpl.java	Mon Apr 15 15:38:47 2019 +0200
+++ b/src/java.base/share/classes/sun/nio/ch/FileChannelImpl.java	Tue Apr 09 16:21:20 2019 +0100
@@ -940,14 +940,15 @@
         if (size > Integer.MAX_VALUE)
             throw new IllegalArgumentException("Size exceeds Integer.MAX_VALUE");
 
-        int imode = -1;
+        int imode;
         if (mode == MapMode.READ_ONLY)
             imode = MAP_RO;
         else if (mode == MapMode.READ_WRITE)
             imode = MAP_RW;
         else if (mode == MapMode.PRIVATE)
             imode = MAP_PV;
-        assert (imode >= 0);
+        else
+            throw new UnsupportedOperationException();
         if ((mode != MapMode.READ_ONLY) && !writable)
             throw new NonWritableChannelException();
         if (!readable)