Name: krT82822 Date: 05/30/99


The documentation for java.io.DataInputStream.read says
  "See the general contract of the read method of DataInput."
but interface DataInput has no such method, only readFully.
See
http://java.sun.com/products/jdk/1.2/docs/api/java/io/DataInputStream.html
and

http://java.sun.com/products/jdk/1.2/docs/api/java/io/DataInput.html

------------------

kevin.ryan@eng, 5/30/99 -- believe the "general contract" is meant to be the overview near the beginning of the interface description:

"It is generally true of all the reading routines in this interface that if end of file is reached before the desired
number of bytes has been read, an EOFException (which is a kind of IOException) is thrown. If any byte
cannot be read for any reason other than end of file, an IOException other than EOFException is thrown. In
particular, an IOException may be thrown if the input stream has been closed."

We should clarify which part of the document(s) we're referring to when we say "general contract".
(Review ID: 83665)
======================================================================

5/31/99 kevin.ryan@eng -- follow-up comments from the user:

I'm afraid you may have misunderstood the main point of my bug report.

So far as I can tell, there is now no place in the documentation that
says what InputStream.read() ACTUALLY DOES. In particular, there is no
explanation of how read() is different from readFully().

Based on the 1.1 documentation and my intuition about the meaning of the
English word "fully", I assume that read() may return less than the amount of
data requested because in.available() returns a value less than the amount
requested. Based on the 1.1 documentation, my experience with Unix, and my
intuition of what semantics would be useful, I assume that read never returns
zero unless the amount requested is zero.

However, this is all guesswork since there does not appear to be any
documentation anywhere.

The long and thorough doc comments in the source of the reference implementation
of InputStream confirm these guesses. However, those comments appear to
have been deleted from documentation release and replaced by a pointer to the
non-existent DataInput.read().

BTW, while you're fixing the docs, note that FilterInputStream#available()
says "This method simply performs in.available(n) and returns the result."
There is, of course, no such method as available(n).

------

P.S. Here's another one, from DataInput.html#skipBytes(int)

"skipBytes

... This method never throws an EOFException.
...
     Throws:
         EOFException - if this stream reaches the end before skipping all the bytes."

Huh?