(fc) Support implementation-defined Map Modes

Summary

The current MapMode enum in class FileChannel encodes a fixed set of modes to configure mapping of persistent storage into memory. However, proposed implementations of FileChannel will require extra modes.

Problem

JEP 352 poses a requirement for implementations of FileChannel to support extra MapMode values in calls to FileChannel.map. There is no need to provide a public API to construct these new values as they can be constructed internally to the JDK runtime. However, the javadoc specification of MapMode and FileChannel.map must change to note for the existence of such values and the javadoc for FileChannel.map needs its exception signature updated to include UnsupportedOperationException, thrown if an unrecognized value is passed.

Solution

Update the javadoc for FileChanel.MapMode and FileChannel.map accordingly.

Specification

Change the javadoc description for FileChannel.MapMode

     /**
-     * A typesafe enumeration for file-mapping modes.
+     * A file-mapping mode.
. . .

Change the javadoc description for FileChannel.map to mention other modes

     /**
      * 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>
 . . .
      *
      *
      * </ul>
      *
+     * <p> An implementation may support additional map modes.
+     *

Document the possibility of passing additional modes

      *         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
      *
. . .

Extend documentation of existing error cases to allow for additional modes

      * @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
. . .

Document possibility of UnsupportedOperationException

+     * @throws UnsupportedOperationException
+     *         If an unsupported map mode is specified
+     *
. . .