8221397: Support implementation-defined Map Modes
Summary: Allow implementation-defined extensions to FileChannel MapMode enum
Reviewed-by: alanb
--- 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)