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

[Bernd Eckenfels]

Hello,

I think "seeking negatively" is a bad example for an IO
problem. For this reason alone I would remove it.

It is unclear to me if this is really forbidden in the interface or in
any implementation. With FileInputStream skip(-5) works.

(I would expect it to throw IllegalArgumentException or
UnsupportedOperationExeption instead.)

Gruss
Bernd


 Am Fri, 3 Jun 2016 09:36:11 -0700
schrieb Brian Burkhalter <brian.burkhalter at oracle.com>:

> Hi Pavel,
> 
> On Jun 3, 2016, at 3:43 AM, Pavel Rappo <pavel.rappo at oracle.com>
> wrote:
> 
> > I have a minor question though:
> > 
> > --- a/src/java.base/share/classes/java/io/InputStream.java
> > +++ b/src/java.base/share/classes/java/io/InputStream.java
> > 
> > -     * @exception  IOException  if the stream does not support
> > seek,
> > -     *                          or if some other I/O error occurs.
> > +     * @throws     IOException  if an I/O error occurs, such as
> > attempting to
> > +     *             seek to a negative position in a seek-based
> > implementation.
> > 
> > Do we need to mention (even as an example) a case of passing a
> > negative integer position to `seek` function?
> 
> Probably not. Do you or anyone else this this example should be
> removed?
> 
> > The only place where I've found this happens is in
> > java.io.RandomAccessFile#seek
> > 
> > public void seek(long pos) throws IOException {
> >    if (pos < 0) {
> >        throw new IOException("Negative seek offset");
> >    } else {
> >        seek0(pos);
> >    }
> > }
> > 
> > But this class is not even in the InputStream hierarchy.
> 
> There can be places outside the JDK:
> 
> http://download.java.net/media/jai/javadoc/1.1.3/jai-apidocs/com/sun/media/jai/codec/SeekableStream.html#seek%28long%29
> 
> > But even if someone
> > decides to use seek, can't they choose some other strategy of
> > dealing with negative arguments?
> 
> Yes, they could.
> 
> I concur that the example is not necessary but it is harmless.
> Comments?
> 
> Thanks,
> 
> Brian