JDK 9 RFR of JDK-8136738: InputStream documentation for IOException in skip() is unclear or incorrect

[Colin Decker]

Isn't this change actually changing the contract of skip()? It's currently
legal for an implementation of skip() may throw IOException if it doesn't
support skip(), and it seems likely that there are implementations out
there that do this. I don't think the description of how InputStream itself
happens to implement the method implies anything about what subclasses
should do, particularly given that there's this @throws statement that
*explicitly* allows subclasses to throw IOException.

Note that I don't think that it's a good design as-is, particularly given
that there's no way to distinguish between an IOException caused by skip()
not being supported and one caused by an actual I/O error, but I'm not sure
why it's ok to change the contract out from under implementations at this
point either.

On Fri, Jun 3, 2016 at 3:39 PM Pavel Rappo <pavel.rappo at oracle.com> wrote:

> Perfect!
>
> > On 3 Jun 2016, at 20:20, Roger Riggs <Roger.Riggs at oracle.com> wrote:
> >
> > +1
> >
> >
> > On 6/3/2016 3:15 PM, Brian Burkhalter wrote:
> >> So if I make this change to the webrev
> >>
> >> --- a/src/java.base/share/classes/java/io/InputStream.java
> >> +++ b/src/java.base/share/classes/java/io/InputStream.java
> >> @@ -333,8 +333,7 @@
> >>      *
> >>      * @param     n   the number of bytes to be skipped.
> >>      * @return     the actual number of bytes skipped.
> >> -     * @throws     IOException  if an I/O error occurs, such as
> attempting to
> >> -     *     seek to a negative position in a seek-based implementation.
> >> +     * @throws     IOException  if an I/O error occurs.
> >>      */
> >>     public long skip(long n) throws IOException {
> >>
> >> do we have consensus?
> >>
> >> Thanks,
> >>
> >> Brian
> >>
> >> On Jun 3, 2016, at 11:34 AM, Pavel Rappo <pavel.rappo at oracle.com
> <mailto:pavel.rappo at oracle.com>> wrote:
> >>
> >>>
> >>>> On 3 Jun 2016, at 19:30, Bernd Eckenfels <ecki at zusammenkunft.net
> <mailto:ecki at zusammenkunft.net>> wrote:
> >>>>
> >>>> It is unclear to me if this is really forbidden in the interface or in
> >>>> any implementation. With FileInputStream skip(-5) works.
> >>>
> >>> Don't mistake `seek` for `skip`. `skip` can be implemented using
> `read`, but
> >>> may be using `seek`.
> >>>
> >>> Here's the API point of view:
> >>>
> >>>   * If {@code n} is
> >>>   * negative, the {@code skip} method for class {@code InputStream}
> always
> >>>   * returns 0, and no bytes are skipped. Subclasses may handle the
> negative
> >>>   * value differently.
> >>>
> >>> Thanks,
> >>> -Pavel
> >>>
> >>>
> >>
> >
>
>