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: import java.util.*;
25:
26: /**
27: * Defines the interface for an output segment, which is used in an {@link OutputDocument} to
28: * replace segments of the source document with other text.
29: * <p>
30: * All text in the <code>OutputDocument</code> between the character positions defined by {@link #getBegin()} and {@link #getEnd()}
31: * is replaced by the content of this output segment.
32: * If the begin and end character positions are the same, the content is simply
33: * inserted at this position without replacing any text.
34: *
35: * @see OutputDocument#register(OutputSegment)
36: */
37: public interface OutputSegment extends CharStreamSource {
38:
39: /**
40: * The comparator used to sort output segments in the {@link OutputDocument} before output.
41: * <p>
42: * The following rules are applied in order compare two output segments:
43: * <ol>
44: * <li>The output segment that {@linkplain #getBegin() begins} earlier in the document comes first.
45: * <li>If both output segments begin at the same position, the one that has zero length comes first.
46: * If neither or both have zero length then neither is guaranteed to come before the other.
47: * </ol>
48: * <p>
49: * Note: this comparator has a natural ordering that may be inconsistent with the <code>equals</code>
50: * method of classes implementing this interface.
51: * This means that the comparator may treat two output segments as equal where calling the
52: * <code>equals(Object)</code> method with the same two output segments returns <code>false</code>.
53: */
54: public static final Comparator COMPARATOR = new OutputSegmentComparator();
55:
56: /**
57: * Returns the character position in the {@linkplain OutputDocument#getSourceText() source text of the output document} where this segment begins.
58: * @return the character position in the {@linkplain OutputDocument#getSourceText() source text of the output document} where this segment begins.
59: */
60: public int getBegin();
61:
62: /**
63: * Returns the character position in the {@linkplain OutputDocument#getSourceText() source text of the output document} where this segment ends.
64: * @return the character position in the {@linkplain OutputDocument#getSourceText() source text of the output document} where this segment ends.
65: */
66: public int getEnd();
67:
68: /**
69: * Writes the content of this output segment to the specified <code>Writer</code>.
70: * @param writer the destination <code>java.io.Writer</code> for the output.
71: * @throws IOException if an I/O exception occurs.
72: */
73: public void writeTo(Writer writer) throws IOException;
74:
75: /**
76: * Returns the content of this output segment as a <code>String</code>.
77: * <p>
78: * Note that before version 2.0 this returned a representation of this object useful for debugging purposes,
79: * which can now be obtained via the {@link #getDebugInfo() getDebugInfo()} method.
80: *
81: * @return the content of this output segment as a <code>String</code>, guaranteed not <code>null</code>.
82: * @see #writeTo(Writer)
83: */
84: public String toString();
85:
86: /**
87: * Returns a string representation of this object useful for debugging purposes.
88: * @return a string representation of this object useful for debugging purposes.
89: */
90: public String getDebugInfo();
91: }
|