Hi, Joe. Thanks for replying.
No, my complaint is not so much that the readObject() method does not
declare that it throws an EOFException, but rather that the documentation does not tell us that the readObject() method actually
will throw an EOFException upon reaching the end of the file.
Of course the declaration makes sense; polymorphism allows subclasses to be thrown via the declaration of superclasses, and this is nicer than declaring all the possible subclasses that could happen. I understand that.
The problem is that the documentation does not tell us as developers/users what will happen under a really common situation, reaching the end of a file. It really should, because it's a really bad habit to infer behavior from other functions that might have somewhat parallel functionality. Don't you agree?
So, I am aware of the documentation for
other methods, like those that read primatives, and I know what they do, because the API helpfully tells me. However, the API for some reason neglects to say it about readObject(), which by the name, one might guess is the centrally important function to a class named "ObjectInputStream".
As for the interface documentation for the DataInput interface, yes, that actually is very helpful. Thank you for pointing that out. I read the documentation for the superclasses, but I neglected to read the documentation for the interfaces.
However, since an Interface declaration cannot determine the actual behavior of the ultimate implementation, the following assertion is still not going to tell me that I should believe that readObject() will throw EOFExceptions:
It is generally true of all the reading methods 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.
"generally" could mean that all of the read methods except readObject throw the EOFException at EOF. I just don't know.
But I'm not trying to be nitpicky with you, Joe. I'm really just wanting to emphasize that, even looking to the interface documentation, the behavior of readObject() is not really clear. My real complaint is that I wish the API just said that, instead of me having to research it all over the class and interface hierarchy.
So, if anyone from Sun is reading, I'm just requesting that in Java 6 API, if you tell us that readBoolean, readInt, readByte, etc. all throw EOFException at EOF, and readObject does the same thing, why not say so there too?
Thanks, Joe, for your feedback and suggestions.
Kentaro.