au.id.jericho.lib.html.CharStreamSource Maven / Gradle / Ivy
// Jericho HTML Parser - Java based library for analysing and manipulating HTML
// Version 2.3
// Copyright (C) 2006 Martin Jericho
// http://sourceforge.net/projects/jerichohtml/
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// http://www.gnu.org/copyleft/lesser.html
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
package au.id.jericho.lib.html;
import java.io.*;
/**
* 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 {@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 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 {@link CharStreamSourceUtil#toString(CharStreamSource)} method converts a CharStreamSource into a String.
* Every class implementing CharStreamSource should include a toString() method that calls
* {@link CharStreamSourceUtil#toString(CharStreamSource) CharStreamSourceUtil.toString(this)}, so that the data can be obtained as a string simply by
* calling charStreamSource.toString().
*
* @see OutputDocument
* @see Source#indent(String,boolean,boolean,boolean) Source.indent
*/
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;
/**
* 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.
*
* @return the estimated maximum number of characters in the output, or -1 if no estimate is available.
*/
long getEstimatedMaximumOutputLength();
}