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

Clarify Reader.skip behavior for end of stream

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P4
    • 17
    • core-libs
    • None
    • behavioral
    • minimal
    • No risk as the change is only to make existing verbiage more precise.
    • Java API
    • SE

    Description

      Summary

      Explicitly specify the behavior of Reader.skip(long) at end-of-stream.

      Problem

      The specification of the behavior of Reader.skip(long) at end-of-stream is insufficiently clear to some readers. For example some could think that -1 is returned if the method is invoked when the reader is already at end-of-stream.

      Solution

      Update the specification of Reader.read(long) and its overrides to specify clearly the behavior at end-of-stream.

      Specification

      A normative specdiff and a webrev are attached.

      The text of Reader.skip() is updated and the subclasses inherit all or part of this text. In subclasses which have only

      /**
       * {@inheritDoc}
       */

      as the specification of skip(long), the method will no longer appear in the main method summary, but rather in the section "Methods declared in class java.io.Reader". This is the case for BufferedReader, LineNumberReader, and PushbackReader. The specifications of skip(long) in the other subclasses add some value however so their verbiage is not entirely inherited. FilterReader provides different text for its @throws clause for IllegalArgumentException, while CharArrayReader and StringReader provide their own verbiage except for their @param, @return, and @throws tags which inherit their respective descriptions.

      Attachments

        1. specdiff-8247918.zip
          204 kB
        2. specdiff-8247918-01.zip
          203 kB
        3. webrev-8247918.zip
          246 kB
        4. webrev-8247918-01.zip
          247 kB

        Issue Links

          Activity

            People

              bpb Brian Burkhalter
              webbuggrp Webbug Group
              Naoto Sato, Roger Riggs
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: