Question about InputStream.reset Contract and Behavior

[Mathias Ricken]

Hi,

 

My team at OCI is trying to correctly implement retries for stream uploads, and we’ve come across the following comment in InputStream.reset():

 

https://docs.oracle.com/javase/7/docs/api/java/io/InputStream.html#reset()

 

If the method markSupported returns true, then: 

·         If the method mark has not been called since the stream was created, or the number of bytes read from the stream since mark was last called is larger than the argument to mark at that last call, then an IOException might be thrown. 

·         If such an IOException is not thrown, then the stream is reset to a state such that all the bytes read since the most recent call to mark (or since the start of the file, if mark has not been called) will be resupplied to subsequent callers of the read method, followed by any bytes that otherwise would have been the next input data as of the time of the call to reset. 

 

(emphasis mine)

 
We would like to know if not getting an IOException guarantees that the stream was successfully reset (as the 2nd bullet point implies).
That probably leads to this interpretation of the “might”: There are situations where (1) mark was called, (2) more bytes were read from the stream than the argument to mark, meaning (3) it wasn’t guaranteed that the stream could be correctly reset, but (4) the stream was in fact reset successfully, and that’s why no IOException was thrown (which is one interpretation of the “might” in the first bullet point).
Or is there a case in which (1) mark was called, (2) more bytes were read from the stream than the argument to mark, meaning (3) the stream could not be correctly reset, but (4) no IOException is thrown (which is another interpretation of the “might” in the first bullet point).
 

I understand that this is a publicly-extendable class, so there might be bad implementations. But what was the intention, and what do official Oracle implementations of InputStream do?

 

We need to understand the contract in order to implement a correctly behaving stream retry mechanism, or to at least fail visibly (a silent failure as (2) above would make possible could lead to silent data corruption).

 

Thanks for your help.

 

Mathias Ricken

Consultant Member of Technical Staff

Oracle Cloud Infrastructure