JDK-8226385 : (bf) MappedByteBuffer.force method may have no effect on implementation specific map modes
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.nio
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 13
  • Submitted: 2019-06-19
  • Updated: 2019-06-20
  • Resolved: 2019-06-20
Related Reports
CSR :  
Description
Summary
-------

Update MappedByteBuffer.force javadoc to encompass implementtaion-specific map modes

Problem
-------

JDK-8221397 allowed for a MappedByteBuffer to be mapped using an implementation-specific map mode. The javadoc for force was not updated to explain that a request may complete with no effect in such a case.

Solution
--------

Update the javadoc to include this outcome.

Specification
-------------

    @@ -232,13 +232,13 @@
          * invoked, will have been written to that device.
          *
          * <p> If the file does not reside on a local device then no such guarantee
          * is made.
          *
    -     * <p> If this buffer was not mapped in read/write mode ({@link
    -     * java.nio.channels.FileChannel.MapMode#READ_WRITE}) then invoking this
    -     * method has no effect. </p>
    +     * <p> This method has no effect for buffers mapped in read-only
    +     * or private mapping modes. It may also have no effect for other
    +     * implementation specific map modes. </p>
          *
          * @return  This buffer
          */
         public final MappedByteBuffer force() {
             if (fd == null) {
    
    @@ -267,13 +267,13 @@
          * are transferred in their entirety.
          *
          * <p> If the file does not reside on a local device then no such
          * guarantee is made.
          *
    -     * <p> If this buffer was not mapped in read/write mode ({@link
    -     * java.nio.channels.FileChannel.MapMode#READ_WRITE}) then
    -     * invoking this method has no effect. </p>
    +     * <p> This method has no effect for buffers mapped in read-only
    +     * or private mapping modes. It may also have no effect for other
    +     * implementation specific map modes. </p>
          *
          * @param index
          *        The index of the first byte in the buffer region that is
          *        to be written back to storage; must be non-negative
          *        and less than limit()

Comments
Moving to Approved. As a code review comment, I suggest keeping the explicit text about when the method has an effect. For example, "If this buffer was not mapped in read/write mode ({@link java.nio.channels.FileChannel.MapMode#READ_WRITE}) then invoking this method has no effect. In particular, note that this method has no effect for buffers mapped in read-only, private, and implementation-specific mapping modes." Or if the method may or may not have an effect on implementation-specific modes, something like: "If this buffer was not mapped in read/write mode ({@link java.nio.channels.FileChannel.MapMode#READ_WRITE}) then invoking this method may have no effect. In particular, the method has no effect for buffers mapped in read-only or private mapping modes. This method may or may not have an effect for implementation-specific mapping modes." I'll let you work out final wording with [~alanb] and other reviewers. HTH
20-06-2019