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

Clarify Reader.skip behavior for end of stream

XMLWordPrintable

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

      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.

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

              Created:
              Updated:
              Resolved: