Represents a character stream source.
The main purpose of a class that implements this interface is to output a stream of characters.
By implementing this interface, the "active" stream source can easily be converted into a "passive" stream source if required by the class needing to consume the data.
An
active stream source is a stream source that actively outputs to a passive receiver ("sink").
The
writeTo(Writer) method in this interface signifies an active source as the transmission of the entire data stream takes place when this method is executed.
In this case the sink is the object that supplies the
Writer object, and would typically contain a
getWriter() method.
The sink is passive because it just supplies a
Writer object to be written to by the code in some other class.
A
passive stream source is a stream source that is read from by an active sink.
For character streams, a passive stream source simply supplies a
Reader object.
The active sink would typically contain a
readFrom(Reader) method which actively reads the entire data stream from the
Reader object.
The
CharStreamSourceUtil.getReader(CharStreamSource) method coverts a
CharStreamSource into a
Reader,
allowing the data from the active
CharStreamSource to be consumed by an active sink with a
readFrom(Reader) method.
The
CharStreamSourceUtil.toString(CharStreamSource) method converts a
CharStreamSource into a
String.
Every class implementing
CharStreamSource should include a
toString() method that calls
CharStreamSourceUtil.toString(this), so that the data can be obtained as a string simply by
calling
charStreamSource.toString().