| Represents a character stream source. The purpose of a class that implements this interface is to output text.
For small amounts of data, or when memory usage isn't a prime concern (e.g. in client-side applications), the simplest way to obtain the data is by calling
the
CharStreamSource.toString() method.
If the character stream might contain a large amount of data it is recommended to use the
CharStreamSource.writeTo(Writer) method to access the data,
especially if running in a multi-user server environment.
The advantage of providing textual data via this interface is that it gives the user the choice as to whether they would like to receive the data as a stream
of characters, or all as a single string. Furthermore, it allows the "active" stream source (see below) to be easily converted into a "passive" stream source
if required.
An active stream source is a stream source that actively outputs to a passive receiver ("sink").
The
CharStreamSource.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 converts a CharStreamSource into a Reader,
allowing the data from the active CharStreamSource to be consumed by an active sink with a readFrom(Reader) method.
Every implementing class must override the
CharStreamSource.toString() method to return the output as a string.
An easy way to implement this is by calling the
CharStreamSourceUtil.toString(CharStreamSource) CharStreamSourceUtil.toString(this) method,
which buffers the output from the
CharStreamSource.writeTo(Writer) method into a string.
See Also: OutputDocument
See Also: SourceFormatter
See Also: Renderer
See Also: TextExtractor |