KickJava   Java API By Example, From Geeks To Geeks.

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


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 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      * <li>If both output segments are zero-length, neither is guaranteed to come before the other.
47      * <li>If neither segment is zero-length, the result is undefined as the segments are overlapping.
48      * Note that this condition is detected at a later stage, so this comparator returns normally without throwing a
49      * {@link OverlappingOutputSegmentsException}.
50      * </ol>
51      * <p>
52      * Note: this comparator has a natural ordering that may be inconsistent with the <code>equals</code>
53      * method of classes implementing this interface.
54      * This means that the comparator may treat two output segments as equal where calling the
55      * <code>equals(Object)</code> method with the same two output segments returns <code>false</code>.
56      */
57     public static final Comparator COMPARATOR=new OutputSegmentComparator();
58
59     /**
60      * Returns the character position in the {@linkplain OutputDocument#getSourceText() source text of the output document} where this segment begins.
61      * @return the character position in the {@linkplain OutputDocument#getSourceText() source text of the output document} where this segment begins.
62      */
63     public int getBegin();
64
65     /**
66      * Returns the character position in the {@linkplain OutputDocument#getSourceText() source text of the output document} where this segment ends.
67      * @return the character position in the {@linkplain OutputDocument#getSourceText() source text of the output document} where this segment ends.
68      */
69     public int getEnd();
70
71     /**
72      * Writes the content of this output segment to the specified <code>Writer</code>.
73      * @param writer the destination <code>java.io.Writer</code> for the output.
74      * @throws IOException if an I/O exception occurs.
75      */
76     public void writeTo(Writer writer) throws IOException;
77
78     /**
79      * Returns the content of this output segment as a <code>String</code>.
80      * <p>
81      * Note that before version 2.0 this returned a representation of this object useful for debugging purposes,
82      * which can now be obtained via the {@link #getDebugInfo() getDebugInfo()} method.
83      *
84      * @return the content of this output segment as a <code>String</code>, guaranteed not <code>null</code>.
85      * @see #writeTo(Writer)
86      */
87     public String JavaDoc toString();
88
89     /**
90      * Returns a string representation of this object useful for debugging purposes.
91      * @return a string representation of this object useful for debugging purposes.
92      */
93     public String JavaDoc getDebugInfo();
94 }
95
Popular Tags