SYNOPSIS
--------
PipedOutputStream/PipedInputStream API documentation needs to be updated

PROBLEM DESCRIPTION from LICENSEE
---------------------------------
The API documentation for the java.io.PipedOutputStream and java.io.PipedInputStream classes should be updated to reflect the fact that it only functions properly with a single reader thread and a single writer thread, as discussed in CR 4028322. The evaluation for that CR indicated that the documentation would be updated, but 14 years has passed and the documentation remains ambiguous, and it still makes no mention of the fact that multiple reading/writing threads are not properly supported.

The documentation should also make it clear that the NIO Pipe implementation (java.nio.channels.Pipe) *does* support multiple threads, and that it should be used in place of the old IO implementation when this functionality is required.

We realise that this is an age old issue and that the documentation has existed in its current form for a very long time, but we still have customers hitting the problem in the field on a regular basis (after attempting to use multiple reading/writing threads). It would be most beneficial for everyone if the API documentation was more accurate.

SUGGESTED FIX
-------------
Two points should be made clear:

1. The PipedOutputStream/PipedInputStream implementations only support a
   single writing thread, and a single reading thread. Multiple
   reading/writing threads are not supported.

2. The java.nio.channels.Pipe supports multiple reading/writing threads