1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24 package net.sf.stax;
25
26 import org.xml.sax.Locator;
27 import org.xml.sax.Attributes;
28 import org.xml.sax.SAXException;
29
30 /***
31 * Receive notification of the logical content of a sub-tree
32 * of a document and provide access to delegation and id mapping services.
33 *
34 * <ol>
35 * <li>start/endDocument methods are replaced by start/endTree. This
36 * recognises the fact that a StAX content handler may only see
37 * a sub-tree of an XML document, rather than the whole document.</li>
38 * <li>the startElement method takes a <code>StAXDelegationContext</code>,
39 * allowing delegation of sub-trees to other content handlers.</li>
40 * <li>all other methods take a <code>StAXContext</code>, allowing
41 * for the mapping of XML ids to java objects.
42 * </ol>
43 *
44 *
45 * @author Thomas Down
46 * @author Matthew Pocock
47 * @author Michael Heuer
48 * @version $Revision: 1.3 $ $Date: 2006/01/02 20:37:34 $
49 */
50 public interface StAXContentHandler
51 {
52 /***
53 * No-op instance of StAXContentHandler.
54 */
55 StAXContentHandler IGNORE = new StAXContentHandlerBase();
56
57 /***
58 * Receive notification of the beginning of a sub-tree of a document.
59 *
60 * @param ctx StAX context
61 * @throws SAXException any SAX exception, possibly wrapping another exception
62 */
63 void startTree(StAXContext ctx)
64 throws SAXException;
65
66 /***
67 * Receive notification of the end of a sub-tree of a document.
68 *
69 * @param ctx StAX context
70 * @return return value
71 * @throws SAXException any SAX exception, possibly wrapping another exception
72 */
73 Object endTree(StAXContext ctx)
74 throws SAXException;
75
76 /***
77 * Receive notification of character data.
78 *
79 * @param ch characters from the XML document
80 * @param start start position in the array
81 * @param length number of characters to read from the array
82 * @param ctx StAX context
83 * @throws SAXException any SAX exception, possibly wrapping another exception
84 */
85 void characters(char[] ch,
86 int start,
87 int length,
88 StAXContext ctx)
89 throws SAXException;
90
91 /***
92 * Receive notification of ignorable whitespace in element content.
93 *
94 * @param ch characters from the XML document
95 * @param start start position in the array
96 * @param length number of characters to read from the array
97 * @param ctx StAX context
98 * @throws SAXException any SAX exception, possibly wrapping another exception
99 */
100 void ignorableWhitespace(char[] ch,
101 int start,
102 int length,
103 StAXContext ctx)
104 throws SAXException;
105
106 /***
107 * Begin the score of a prefix-URI Namespace mapping.
108 *
109 * @param prefix namespace prefix being declared
110 * @param uri namespace URI the prefix is mapped to
111 * @param ctx StAX context
112 * @throws SAXException any SAX exception, possibly wrapping another exception
113 */
114 void startPrefixMapping(String prefix,
115 String uri,
116 StAXContext ctx)
117 throws SAXException;
118
119 /***
120 * End the scope of a prefix-URI mapping.
121 *
122 * @param prefix prefix that was being mapped
123 * @param ctx StAX context
124 * @throws SAXException any SAX exception, possibly wrapping another exception
125 */
126 void endPrefixMapping(String prefix, StAXContext ctx)
127 throws SAXException;
128
129 /***
130 * Receive notification of a processing instruction.
131 *
132 * @param target processing instruction target
133 * @param data processing instruction data
134 * @param ctx StAX context
135 * @throws SAXException any SAX exception, possibly wrapping another exception
136 */
137 void processingInstruction(String target, String data, StAXContext ctx)
138 throws SAXException;
139
140 /***
141 * Receive an object for locating the origin of SAX document events.
142 *
143 * @param locator an object that can return the location of any SAX document event
144 * @param ctx StAX context
145 */
146 void setDocumentLocator(Locator locator, StAXContext ctx);
147
148 /***
149 * Receive notification of a skipped entity.
150 *
151 * @param name name of the skipped entity
152 * @param ctx StAX context
153 * @throws SAXException any SAX exception, possibly wrapping another exception
154 */
155 void skippedEntity(String name, StAXContext ctx)
156 throws SAXException;
157
158 /***
159 * Receive notification of the beginning of an element.
160 *
161 * @param nsURI namespace URI
162 * @param localName local name (without prefix)
163 * @param qName qualified XML name (with prefix)
164 * @param attrs attributes attached to the element
165 * @param dctx StAX delegation context
166 * @throws SAXException any SAX exception, possibly wrapping another exception
167 */
168 void startElement(String nsURI,
169 String localName,
170 String qName,
171 Attributes attrs,
172 StAXDelegationContext dctx)
173 throws SAXException;
174
175 /***
176 * Receive notification of the end of an element.
177 *
178 * @param nsURI namespace URI
179 * @param localName local name (without prefix)
180 * @param qName qualified XML name (with prefix)
181 * @param result result
182 * @param ctx StAX context
183 * @throws SAXException any SAX exception, possibly wrapping another exception
184 */
185 void endElement(String nsURI,
186 String localName,
187 String qName,
188 Object result,
189 StAXContext ctx)
190 throws SAXException;
191 }