// Jericho HTML Parser - Java based library for analysing and manipulating HTML
// Version 2.5
// Copyright (C) 2007 Martin Jericho
// http://jerichohtml.sourceforge.net/
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of either one of the following licences:
//
// 1. The Eclipse Public License (EPL) version 1.0,
// included in this distribution in the file licence-epl-1.0.html
// or available at http://www.eclipse.org/legal/epl-v10.html
//
// 2. The GNU Lesser General Public License (LGPL) version 2.1 or later,
// included in this distribution in the file licence-lgpl-2.1.txt
// or available at http://www.gnu.org/licenses/lgpl.txt
//
// This library is distributed on an "AS IS" basis,
// WITHOUT WARRANTY OF ANY KIND, either express or implied.
// See the individual licence texts for more details.

package au.id.jericho.lib.html;

import java.io.*;

/**
 * Represents a character stream source.  The purpose of a class that implements this interface is to output text.
 * <p>
 * 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.
 * <p>
 * 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.
 * <p>
 * An <i><a name="Active">active stream source</a></i> 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 <code>Writer</code> object, and would typically contain a <code>getWriter()</code> method.
 * The sink is passive because it just supplies a <code>Writer</code> object to be written to by the code in some other class.
 * <p>
 * A <i><a name="Passive">passive stream source</a></i> is a stream source that is read from by an active sink.
 * For character streams, a passive stream source simply supplies a <code>Reader</code> object.
 * The active sink would typically contain a <code>readFrom(Reader)</code> method which actively reads the entire data stream from the <code>Reader</code> object.
 * <p>
 * The {@link CharStreamSourceUtil#getReader(CharStreamSource)} method converts a <code>CharStreamSource</code> into a <code>Reader</code>,
 * allowing the data from the active <code>CharStreamSource</code> to be consumed by an active sink with a <code>readFrom(Reader)</code> method.
 * <p>
 * Every implementing class must override the {@link #toString()} method to return the output as a string.
 * <p>
 * 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 <code>Writer</code>.
	 *
	 * @param writer  the destination <code>java.io.Writer</code> 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 <code>-1</code> if no estimate is available.
	 * <p>
	 * The returned value should be used as a guide for efficiency purposes only, for example to set an initial <code>StringBuffer</code> 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 <code>-1</code> if no estimate is available.
	 */
	long getEstimatedMaximumOutputLength();

	/**
	 * Returns the output as a string.
	 * @return the output as a string.
	 */
	String toString();
}
