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.
- csr of
-
JDK-8247918 Clarify Reader.skip behavior for end of stream
-
- Resolved
-