* 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 {@link #toString()} method. * If the character stream might contain a large amount of data it is recommended to use the {@link #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 {@link #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 {@link 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 {@link #toString()} method to return the output as a string. *
* An easy way to implement this is by calling the {@link CharStreamSourceUtil#toString(CharStreamSource) CharStreamSourceUtil.toString(this)} method,
* which buffers the output from the {@link #writeTo(Writer)} method into a string.
*
* @see OutputDocument
* @see SourceFormatter
* @see Renderer
* @see TextExtractor
*/
public interface CharStreamSource {
/**
* Writes the output to the specified Writer.
*
* @param writer the destination java.io.Writer for the output.
* @throws IOException if an I/O exception occurs.
*/
void writeTo(Writer writer) throws IOException;
/**
* Appends the output to the specified Appendable object.
*
* @param appendable the destination java.lang.Appendable object for the output.
* @throws IOException if an I/O exception occurs.
*/
void appendTo(Appendable appendable) throws IOException;
/**
* 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 StringBuilder 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.
*
* Although implementations of this method should never return a value less than -1, users of this method must not assume that this will always be the case.
* Standard practice is to interpret any negative value as meaning that no estimate is available.
*
* @return the estimated maximum number of characters in the output, or -1 if no estimate is available.
*/
long getEstimatedMaximumOutputLength();
/**
* Returns the output as a string.
* @return the output as a string.
*/
String toString();
}