Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8222107

(fc) Support implementation-defined Map Modes

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 13
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Hide
      There is a small risk that a new, implementation-specific, enum value appropriate to some given implementation could be passed as argument to another existing implementation and fail to be recognized. There are two possible consequences according to the case handling in the second implementation: it may misinterpret the supplied mode as an expected value or it may generate an exception. This error will only apply to new code that misuses newly defined enum values i.e. new code that is wrongly implemented.
      Show
      There is a small risk that a new, implementation-specific, enum value appropriate to some given implementation could be passed as argument to another existing implementation and fail to be recognized. There are two possible consequences according to the case handling in the second implementation: it may misinterpret the supplied mode as an expected value or it may generate an exception. This error will only apply to new code that misuses newly defined enum values i.e. new code that is wrongly implemented.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              adinn Andrew Dinn
              Reporter:
              adinn Andrew Dinn
              Reviewed By:
              Alan Bateman
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: