au.id.jericho.lib.html

Interface CharStreamSource

Known Subinterfaces:
OutputSegment
Known Implementing Classes:
AttributesOutputSegment, OutputDocument, StringOutputSegment

public interface CharStreamSource

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

See Also:
OutputDocument, Source.indent

Method Summary

long
getEstimatedMaximumOutputLength()
Returns the estimated maximum number of characters in the output, or -1 if no estimate is available.
void
writeTo(Writer writer)
Writes the output to the specified Writer.

Method Details

getEstimatedMaximumOutputLength

public long getEstimatedMaximumOutputLength()
Returns the estimated maximum number of characters in the output, or -1 if no estimate is available.

The returned value should be used as a guide for efficiency purposes only, for example to set an initial StringBuffer capacity. There is no guarantee that the length of the output is indeed less than this value, as classes implementing this method often use assumptions based on typical usage to calculate the estimate.

Returns:
the estimated maximum number of characters in the output, or -1 if no estimate is available.

writeTo

public void writeTo(Writer writer)
            throws IOException
Writes the output to the specified Writer.
Parameters:
writer - the destination java.io.Writer for the output.