01: package com.jclark.xml.parse;
02:
03: import java.io.Writer;
04: import java.io.IOException;
05:
06: /**
07: * Information about character data.
08: * There is no guarantee that consecutive characters will
09: * be reported in the same <code>CharacterDataEvent</code>.
10: * Surrogate pairs are guaranteed not to be split across
11: * <code>CharacterDataEvent</code>s.
12: * Line boundaries are normalized to <code>'\n'</code> (ASCII code 10).
13: * @see com.jclark.xml.parse.base.Application#characterData
14: * @version $Revision: 1.6 $ $Date: 1998/06/10 09:43:54 $
15: */
16: public interface CharacterDataEvent {
17: /**
18: * Returns the length in chars of the character data.
19: * A character represented by a pair of surrogate chars
20: * counts as 2 chars.
21: */
22: int getLength();
23:
24: /**
25: * Returns an upper bound on the length of the character data.
26: * The value returned is guaranteed to be greater than or equal the value
27: * returned by <code>getLength</code>.
28: * This can be used to ensure that the buffer passed to
29: * <code>copyChars</code> is large enough;
30: * it is typically much faster to use <code>getLengthMax</code>
31: * than <code>getLength</code> for this.
32: */
33: int getLengthMax();
34:
35: /**
36: * Copies the character data into the specified character array
37: * starting at index <code>off</code>.
38: * The length of the array must be sufficient to hold all the
39: * character data.
40: * @return the number of characters of data
41: * (the same as returned by <code>getLength</code>)
42: */
43: int copyChars(char[] cbuf, int off);
44:
45: /**
46: * Writes the character data to the specified <code>Writer</code>.
47: */
48: void writeChars(Writer writer) throws IOException;
49:
50: /**
51: * Returns true if the character was a result of a character reference
52: * or a predefined entity reference.
53: * If this returns true, then
54: * <code>getLength</code> and <code>getLengthMax</code> will return,
55: * unless the referenced character is represented
56: * as a surrogate pair in which case 2 will be returned.
57: */
58: boolean isReference();
59: }
|