01: // Jericho HTML Parser - Java based library for analysing and manipulating HTML
02: // Version 2.5
03: // Copyright (C) 2007 Martin Jericho
04: // http://jerichohtml.sourceforge.net/
05: //
06: // This library is free software; you can redistribute it and/or
07: // modify it under the terms of either one of the following licences:
08: //
09: // 1. The Eclipse Public License (EPL) version 1.0,
10: // included in this distribution in the file licence-epl-1.0.html
11: // or available at http://www.eclipse.org/legal/epl-v10.html
12: //
13: // 2. The GNU Lesser General Public License (LGPL) version 2.1 or later,
14: // included in this distribution in the file licence-lgpl-2.1.txt
15: // or available at http://www.gnu.org/licenses/lgpl.txt
16: //
17: // This library is distributed on an "AS IS" basis,
18: // WITHOUT WARRANTY OF ANY KIND, either express or implied.
19: // See the individual licence texts for more details.
20:
21: package au.id.jericho.lib.html;
22:
23: import java.io.*;
24:
25: /**
26: * Represents a character stream source. The purpose of a class that implements this interface is to output text.
27: * <p>
28: * 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
29: * the {@link #toString()} method.
30: * 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,
31: * especially if running in a multi-user server environment.
32: * <p>
33: * 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
34: * 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
35: * if required.
36: * <p>
37: * An <i><a name="Active">active stream source</a></i> is a stream source that actively outputs to a passive receiver ("sink").
38: * 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.
39: * In this case the sink is the object that supplies the <code>Writer</code> object, and would typically contain a <code>getWriter()</code> method.
40: * The sink is passive because it just supplies a <code>Writer</code> object to be written to by the code in some other class.
41: * <p>
42: * A <i><a name="Passive">passive stream source</a></i> is a stream source that is read from by an active sink.
43: * For character streams, a passive stream source simply supplies a <code>Reader</code> object.
44: * 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.
45: * <p>
46: * The {@link CharStreamSourceUtil#getReader(CharStreamSource)} method converts a <code>CharStreamSource</code> into a <code>Reader</code>,
47: * allowing the data from the active <code>CharStreamSource</code> to be consumed by an active sink with a <code>readFrom(Reader)</code> method.
48: * <p>
49: * Every implementing class must override the {@link #toString()} method to return the output as a string.
50: * <p>
51: * An easy way to implement this is by calling the {@link CharStreamSourceUtil#toString(CharStreamSource) CharStreamSourceUtil.toString(this)} method,
52: * which buffers the output from the {@link #writeTo(Writer)} method into a string.
53: *
54: * @see OutputDocument
55: * @see SourceFormatter
56: * @see Renderer
57: * @see TextExtractor
58: */
59: public interface CharStreamSource {
60: /**
61: * Writes the output to the specified <code>Writer</code>.
62: *
63: * @param writer the destination <code>java.io.Writer</code> for the output.
64: * @throws IOException if an I/O exception occurs.
65: */
66: void writeTo(Writer writer) throws IOException;
67:
68: /**
69: * Returns the estimated maximum number of characters in the output, or <code>-1</code> if no estimate is available.
70: * <p>
71: * The returned value should be used as a guide for efficiency purposes only, for example to set an initial <code>StringBuffer</code> capacity.
72: * There is no guarantee that the length of the output is indeed less than this value,
73: * as classes implementing this method often use assumptions based on typical usage to calculate the estimate.
74: *
75: * @return the estimated maximum number of characters in the output, or <code>-1</code> if no estimate is available.
76: */
77: long getEstimatedMaximumOutputLength();
78:
79: /**
80: * Returns the output as a string.
81: * @return the output as a string.
82: */
83: String toString();
84: }
|