JDK-8280598 : (fc spec) Unclear spec for FileChannel.force
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.nio
  • Priority: P4
  • Status: Finalized
  • Resolution: Unresolved
  • Fix Versions: 19
  • Submitted: 2022-01-25
  • Updated: 2022-01-25
Related Reports
CSR :  
Description
Summary
-------

Clarify that modifications to a `FileChannel`'s file made via methods of a `FileOutputStream` or `RandomAccessFile` from which the channel was obtained using `getChannel()` are also subject to the effects of `FileChannel.force()`.

Problem
-------

Currently the specification of `FileChannel.force()` states only

`This method is only guaranteed to force changes that were made to this channel's file via the methods defined in this class`

which does not cover the cases where changes made via parent `FileOutputStream` and `RandomAccessFile` methods will also be forced.

Solution
--------

Change the sentence mentioned in the problem statement above to:

`This method is only guaranteed to force changes that were made to this channel's file via the methods defined in this class, or the methods defined by FileOutputStream or RandomAccessFile when the channel was obtained with the getChannel method.`


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

    --- a/src/java.base/share/classes/java/nio/channels/FileChannel.java
    +++ b/src/java.base/share/classes/java/nio/channels/FileChannel.java
    @@ -554,7 +554,9 @@ public abstract class FileChannel
          * actually done is system-dependent and is therefore unspecified.
          *
          * <p> This method is only guaranteed to force changes that were made to
    -     * this channel's file via the methods defined in this class.  It may or
    +     * this channel's file via the methods defined in this class, or the methods
    +     * defined by {@link FileOutputStream} or {@link RandomAccessFile} when the
    +     * channel was obtained with the {@code getChannel} method. It may or
          * may not force changes that were made by modifying the content of a
          * {@link MappedByteBuffer <i>mapped byte buffer</i>} obtained by
          * invoking the {@link #map map} method.  Invoking the {@link