P4
A DESCRIPTION OF THE PROBLEM :
In addition to JDK-7016956, the PipedInputStream and PipedOutputStream classes should be better documented to make it easier for the user to use them.
- Explain in the class docs how connecting the streams works: Connecting one to the other actually connects
both; they cannot be connected to another stream afterwards. Unconnected streams cannot be used for writing or
reading.
There are currently 4 ways of connecting the streams (respective constructors and `connect` methods) and only
the `connect` methods explain it partially.
- Provide examples. Please provide examples showing how the streams can be used, e.g. writing to the
PipedOutputStream from a separate thread and then using the PipedInputStream.
Currently it is rather difficult for the user to understand how these classes might be useful for them
and they have to rely on additional sources.
See also "Why doesn't more Java code use PipedInputStream / PipedOutputStream?" (https://stackoverflow.com/q/484119)
- Clearify that the classes do not use OS pipes.
This is apparently a frequent(?) misconception.
- Mention how important it is to call `close` on BOTH sides after the streams are not needed anymore.
If the user fails to do this they will encounter a broken pipe or infinite blocking. The current `close`
docs could also be improved since they do not mention this.
- Clearify that closing a stream does not result in a broken pipe. The PipedInputStream doc says
> A pipe is said to be broken if a thread that was providing data bytes to the connected piped output stream is no longer alive.
This makes the user think they have to keep the writer thread alive even after they called `close`.
See https://stackoverflow.com/a/1866339
- Fix incorrect PipedOutputStream `flush` documentation. It currently says:
> Flushes this output stream and forces any buffered output bytes to be written out.
There is nothing flushed, only the readers are informed. The current documentation is misleading and
makes users think they have to call `flush`, see https://stackoverflow.com/questions/1866255/pipedinputstream-how-to-avoid-java-io-ioexception-pipe-broken#comment12002432_1867111
----
Such useful classes should have better documentation.
In addition to JDK-7016956, the PipedInputStream and PipedOutputStream classes should be better documented to make it easier for the user to use them.
- Explain in the class docs how connecting the streams works: Connecting one to the other actually connects
both; they cannot be connected to another stream afterwards. Unconnected streams cannot be used for writing or
reading.
There are currently 4 ways of connecting the streams (respective constructors and `connect` methods) and only
the `connect` methods explain it partially.
- Provide examples. Please provide examples showing how the streams can be used, e.g. writing to the
PipedOutputStream from a separate thread and then using the PipedInputStream.
Currently it is rather difficult for the user to understand how these classes might be useful for them
and they have to rely on additional sources.
See also "Why doesn't more Java code use PipedInputStream / PipedOutputStream?" (https://stackoverflow.com/q/484119)
- Clearify that the classes do not use OS pipes.
This is apparently a frequent(?) misconception.
- Mention how important it is to call `close` on BOTH sides after the streams are not needed anymore.
If the user fails to do this they will encounter a broken pipe or infinite blocking. The current `close`
docs could also be improved since they do not mention this.
- Clearify that closing a stream does not result in a broken pipe. The PipedInputStream doc says
> A pipe is said to be broken if a thread that was providing data bytes to the connected piped output stream is no longer alive.
This makes the user think they have to keep the writer thread alive even after they called `close`.
See https://stackoverflow.com/a/1866339
- Fix incorrect PipedOutputStream `flush` documentation. It currently says:
> Flushes this output stream and forces any buffered output bytes to be written out.
There is nothing flushed, only the readers are informed. The current documentation is misleading and
makes users think they have to call `flush`, see https://stackoverflow.com/questions/1866255/pipedinputstream-how-to-avoid-java-io-ioexception-pipe-broken#comment12002432_1867111
----
Such useful classes should have better documentation.
- relates to
-
JDK-7016956 (spec) PipedOutputStream/PipedInputStream should be clear where it supports multiple threads or not
-
- Open
-