Name: ssT124754 Date: 04/04/2001


java version "1.3.0"
Java (TM) 2 Runtime Environment, Standard Edition (build 1.3.0-C)
Java HotSpot (TM) Client VM (build 1.3.0-C mixed mode)


This is a followup to Bug ID: 4429237. This was determined to not be a bug.
However, it has raised some cross platform compatibility issues which I will
address here.

To briefly summarize the relevant parts of 4429237, Process.getOuputStream()
returns an object of type OuputStream, which the documentation specifies is to
be used to communicate with an execed sub-process's input stream (System.in in
the case of a java sub-process).

In at least one implementation, the Intel Win98 version, the OutputStream
returned is buffered in some way, perhaps as a BufferedOutputStream (for
purposes of this discussion, the exact implementation is irrelevant). At any
rate, this OutputStream will never actually send data to the sub-process's
input stream unless the buffer is filled by some arbitrarily defined amount of
data, or OutputStream.flush() is called to flush the data and send it to the
sub-process.

This is not consistant with the behavior of other output streams. For example,
both System.err and FileOutputStream seem to work just fine, without calls to
flush() and without any particular amount of data needing to be written. If
any buffering occurs, it does so in a manner transparent to the programmer.

Within the framework provided by OutputStream's public interface, it would be
perfectly legal for an implementation of Process.getOutputStream() to return an
OutputStream that does not use buffering and does not require a call to flush()
to use. If say the Solaris implementation of Java were to provide a non-
buffered process OutputStream, a programmer could write a program that worked
under Solaris, but did not function under Win98 because it did not call .flush
() to send the data to the sub-process.

Furthermore, if it is reasonable, legal, and acceptable for an implmentation of
Process.getOutputStream() to require .flush() to be called in order to function
properly, it seems that it would also be reasonable, legal, and acceptable for
System.out, System.err, or FileOutputStream to require .flush() in order for
the output to actually reach the console or output file (I admit that I do not
have access to internal implementation requirements and Java Test Suites, so if
these would preclude such a thing, well and good, but it needs to be in the
documentation of the public interface). The actual class of System.out and
System.err is a sub-class of OutputStream, the PrintStream class. While this
class does define an auto-flush option there is nothing within the
documentation that says that this auto-flush option will be enabled. If some
java implementation were to decide to never deliver the data written to
System.err unless System.err.flush() were called, immense confusion would
result and many already existing programs might stop working because they
operate on the implicit assumption that they don't need to call .flush().


I submit that the behavior of OutputStream and all of its sub-classes needs to
be more clearly defined. While the .flush() method exists on output stream, it
is not clearly specified when and whether a programmer would need to use it.
Thus, separate implementations of OutputStream or its sub-classes might result
in a program that works well on one system would not do so on another. To
ensure cross-platform functionality, the contract between OutputStream and the
programmer needs to be revisited. Here is a possibility:

OutputStream and all of its sub-classes (or classes that are defined to return
some type of OutputStream such as Process.getOutputStream(), or System.out)
should have a contract that defines when and whether data will be delivered in
one or more of the following ways:
* Data will be delivered before write() method returns.
* An attempt will be made to deliver the data within X ms. If the buffer has
not been filled within X ms, a Daemon thread will attempt to deliver the data.
The priority at which the thread runs must also be specified (perhaps
OutputStream.DELIVERY_THREAD_PRIORITY), so that the programmer can ensure that
the thread gets to run and that it doesn't use up system resources at the wrong
time.
* An attempt to deliver the data will be made when write() is called, but only
if the least recent data in the buffer is at least X ms old. (From the
viewpoint of ease of programming, this is potentially confusing, but it could
be quite efficient).
* Data will be delivered if at least X bytes of data have been written to the
buffer.
* Data will be delivered if the flush() method is called.
(Review ID: 119930)
======================================================================