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()
.