KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > au > id > jericho > lib > html > CharStreamSource


1 // Jericho HTML Parser - Java based library for analysing and manipulating HTML
2 // Version 2.2
3 // Copyright (C) 2006 Martin Jericho
4 // http://sourceforge.net/projects/jerichohtml/
5 //
6 // This library is free software; you can redistribute it and/or
7 // modify it under the terms of the GNU Lesser General Public
8 // License as published by the Free Software Foundation; either
9 // version 2.1 of the License, or (at your option) any later version.
10 // http://www.gnu.org/copyleft/lesser.html
11 //
12 // This library is distributed in the hope that it will be useful,
13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 // Lesser General Public License for more details.
16 //
17 // You should have received a copy of the GNU Lesser General Public
18 // License along with this library; if not, write to the Free Software
19 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
21 package au.id.jericho.lib.html;
22
23 import java.io.*;
24
25 /**
26  * Represents a character stream source.
27  * <p>
28  * The main purpose of a class that implements this interface is to output a stream of characters.
29  * 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.
30  * <p>
31  * An <i><a name="Active">active stream source</a></i> is a stream source that actively outputs to a passive receiver ("sink").
32  * 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.
33  * In this case the sink is the object that supplies the <code>Writer</code> object, and would typically contain a <code>getWriter()</code> method.
34  * The sink is passive because it just supplies a <code>Writer</code> object to be written to by the code in some other class.
35  * <p>
36  * A <i><a name="Passive">passive stream source</a></i> is a stream source that is read from by an active sink.
37  * For character streams, a passive stream source simply supplies a <code>Reader</code> object.
38  * 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.
39  * <p>
40  * The {@link CharStreamSourceUtil#getReader(CharStreamSource)} method coverts a <code>CharStreamSource</code> into a <code>Reader</code>,
41  * allowing the data from the active <code>CharStreamSource</code> to be consumed by an active sink with a <code>readFrom(Reader)</code> method.
42  * <p>
43  * The {@link CharStreamSourceUtil#toString(CharStreamSource)} method converts a <code>CharStreamSource</code> into a <code>String</code>.
44  * Every class implementing <code>CharStreamSource</code> should include a <code>toString()</code> method that calls
45  * {@link CharStreamSourceUtil#toString(CharStreamSource) CharStreamSourceUtil.toString(this)}, so that the data can be obtained as a string simply by
46  * calling <code>charStreamSource.toString()</code>.
47  * <p>
48  * @see OutputDocument
49  * @see Source#indent(String,boolean,boolean,boolean) Source.indent
50  */
51 public interface CharStreamSource {
52     /**
53      * Writes the output to the specified <code>Writer</code>.
54      *
55      * @param writer the destination <code>java.io.Writer</code> for the output.
56      * @throws IOException if an I/O exception occurs.
57      */
58     void writeTo(Writer writer) throws IOException;
59
60     /**
61      * Returns the estimated maximum number of characters in the output, or <code>-1</code> if no estimate is available.
62      * <p>
63      * The returned value should be used as a guide for efficiency purposes only, for example to set an initial <code>StringBuffer</code> capacity.
64      * There is no guarantee that the length of the output is indeed less than this value,
65      * as classes implementing this method often use assumptions based on typical usage to calculate the estimate.
66      *
67      * @return the estimated maximum number of characters in the output, or <code>-1</code> if no estimate is available.
68      */
69     long getEstimatedMaximumOutputLength();
70 }
71
Popular Tags