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

[Brian Burkhalter]

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