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

(fc spec) FileChannel.write(ByteBuffer, position) behavior when file opened for append not specified

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P4
    • 20
    • core-libs
    • None
    • behavioral
    • minimal
    • The proposed additional verbiage describes longstanding behavior so the risk is minimal.
    • Java API
    • SE

    Description

      Summary

      Document that the absolute write method java.nio.channels.FileChannel(ByteBuffer,long) has unspecified behavior if the file is opened in append mode.

      Problem

      On some platforms invoking an absolute write on a FileChannel opened in append mode might write the sequence of bytes at the specified position in the file, but on other platforms the sequence might be appended to the file and the position parameter ignored. For example, on macOS the sequence of bytes would be written starting at position, but on Linux they would be appended to the file (see JDK-4950302).

      Solution

      Add verbiage clarifying that the behavior of write(ByteBuffer,long) is unspecified when the file was opened with StandardOpenOption.APPEND present.

      Specification

      --- a/src/java.base/share/classes/java/nio/channels/FileChannel.java
      +++ b/src/java.base/share/classes/java/nio/channels/FileChannel.java
      @@ -146,7 +146,9 @@ import jdk.internal.javac.PreviewFeature;
        * operation first advances the position to the end of the file and then writes
        * the requested data.  Whether the advancement of the position and the writing
        * of the data are done in a single atomic operation is system-dependent and
      - * therefore unspecified.
      + * therefore unspecified.  In this mode an invocation of the {@linkplain
      + * #write(ByteBuffer,long) absolute write} operation leads to unspecified
      + * behavior.
        *
        * @see java.io.FileInputStream#getChannel()
        * @see java.io.FileOutputStream#getChannel()
      @@ -193,7 +195,9 @@ public abstract class FileChannel
            *     the position to the end of the file and then writes the requested
            *     data. Whether the advancement of the position and the writing of the
            *     data are done in a single atomic operation is system-dependent and
      -     *     therefore unspecified. This option may not be used in conjunction
      +     *     therefore unspecified. The effect of performing an
      +     *     {@linkplain #write(ByteBuffer,long) absolute write} with this option
      +     *     present is unspecified. This option may not be used in conjunction
            *     with the {@code READ} or {@code TRUNCATE_EXISTING} options. </td>
            * </tr>
            * <tr>
      @@ -809,6 +813,9 @@ public abstract class FileChannel
            * grown to accommodate the new bytes; the values of any bytes between the
            * previous end-of-file and the newly-written bytes are unspecified.  </p>
            *
      +     * <p> If the file is open in <a href="#append-mode">append mode</a>, then
      +     * the effect of invoking this method is unspecified.
      +     *
            * @param  src
            *         The buffer from which bytes are to be transferred
            *

      Attachments

        Issue Links

          Activity

            People

              bpb Brian Burkhalter
              ndcosta Nelson Dcosta (Inactive)
              Alan Bateman
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: