Source code: org/znerd/xmlenc/XMLEventListener.java
1 /*
2 * $Id: XMLEventListener.java,v 1.9 2005/09/12 08:40:02 znerd Exp $
3 */
4 package org.znerd.xmlenc;
5
6 import java.io.IOException;
7 import java.io.UnsupportedEncodingException;
8
9 /**
10 * Interface for XML event listeners.
11 *
12 * <h3>State transitions</h3>
13 *
14 * XML event sources must obey a state model when calling
15 * <code>XMLEventListener</code>s. However, an <code>XMLEventListener</code>
16 * is not required to check that this state model is actually respected. If it
17 * does, then it will throw an {@link IllegalStateException} if the state
18 * model is violated.
19 *
20 * <p>Stateful <code>XMLEventListener</code> implementations should
21 * implement the {@link StatefulXMLEventListener} interface instead of
22 * implementing <code>XMLEventListener</code> directly.
23 *
24 * <p>Initially the state of an uninitialized <code>XMLEventListener</code> is
25 * {@link #UNINITIALIZED UNINITIALIZED}.
26 *
27 * <p>The following table defines how the state changes when a certain
28 * method is called in a certain state. Horizontally are the current states,
29 * vertically the notification methods. The cells self contain the
30 * new state.
31 *
32 * <p><table class="states">
33 * <tr>
34 * <th></th>
35 * <th><acronym title="BEFORE_XML_DECLARATION">S0</acronym></th>
36 * <th><acronym title="BEFORE_DTD_DECLARATION">S1</acronym></th>
37 * <th><acronym title="BEFORE_ROOT_ELEMENT">S2</acronym></th>
38 * <th><acronym title="START_TAG_OPEN">S3</acronym></th>
39 * <th><acronym title="WITHIN_ELEMENT">S4</acronym></th>
40 * <th><acronym title="AFTER_ROOT_ELEMENT">S5</acronym></th>
41 * <th><acronym title="DOCUMENT_ENDED">S6</acronym></th>
42 * </tr>
43 * <tr>
44 * <th>{@link #declaration()}</th>
45 * <td><acronym title="BEFORE_DTD_DECLARATION">S1</acronym></td>
46 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
47 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
48 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
49 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
50 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
51 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
52 * </tr>
53 * <tr>
54 * <th>{@link #dtd(String,String,String)}</th>
55 * <td><acronym title="BEFORE_ROOT_ELEMENT">S2</acronym></td>
56 * <td><acronym title="BEFORE_ROOT_ELEMENT">S2</acronym></td>
57 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
58 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
59 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
60 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
61 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
62 * </tr>
63 * <tr>
64 * <th>{@link #startTag(String)}</th>
65 * <td><acronym title="START_TAG_OPEN">S3</acronym></td>
66 * <td><acronym title="START_TAG_OPEN">S3</acronym></td>
67 * <td><acronym title="START_TAG_OPEN">S3</acronym></td>
68 * <td><acronym title="START_TAG_OPEN">S3</acronym></td>
69 * <td><acronym title="START_TAG_OPEN">S3</acronym></td>
70 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
71 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
72 * </tr>
73 * <tr>
74 * <th>{@link #attribute(String,String)}</th>
75 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
76 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
77 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
78 * <td><acronym title="START_TAG_OPEN">S3</acronym></td>
79 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
80 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
81 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
82 * </tr>
83 * <tr>
84 * <th>{@link #endTag()}</th>
85 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
86 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
87 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
88 * <td><acronym title="WITHIN_ELEMENT">S4</acronym>/<acronym title="AFTER_ROOT_ELEMENT">S5</acronym></td>
89 * <td><acronym title="WITHIN_ELEMENT">S4</acronym>/<acronym title="AFTER_ROOT_ELEMENT">S5</acronym></td>
90 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
91 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
92 * </tr>
93 * <tr>
94 * <th>{@link #pcdata(String)}</th>
95 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
96 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
97 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
98 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
99 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
100 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
101 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
102 * </tr>
103 * <tr>
104 * <th>{@link #pcdata(char[],int,int)}</th>
105 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
106 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
107 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
108 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
109 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
110 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
111 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
112 * </tr>
113 * <tr>
114 * <th>{@link #cdata(String)}</th>
115 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
116 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
117 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
118 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
119 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
120 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
121 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
122 * </tr>
123 * <tr>
124 * <th>{@link #whitespace(String)}</th>
125 * <td><acronym title="BEFORE_DTD_DECLARATION">S1</acronym></td>
126 * <td><acronym title="BEFORE_DTD_DECLARATION">S1</acronym></td>
127 * <td><acronym title="BEFORE_ROOT_ELEMENT">S4</acronym></td>
128 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
129 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
130 * <td><acronym title="AFTER_ROOT_ELEMENT">S5</acronym></td>
131 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
132 * </tr>
133 * <tr>
134 * <th>{@link #whitespace(char[],int,int)}</th>
135 * <td><acronym title="BEFORE_DTD_DECLARATION">S1</acronym></td>
136 * <td><acronym title="BEFORE_DTD_DECLARATION">S1</acronym></td>
137 * <td><acronym title="BEFORE_ROOT_ELEMENT">S4</acronym></td>
138 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
139 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
140 * <td><acronym title="AFTER_ROOT_ELEMENT">S5</acronym></td>
141 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
142 * </tr>
143 * <tr>
144 * <th>{@link #comment(String)}</th>
145 * <td><acronym title="BEFORE_DTD_DECLARATION">S1</acronym></td>
146 * <td><acronym title="BEFORE_DTD_DECLARATION">S1</acronym></td>
147 * <td><acronym title="BEFORE_ROOT_ELEMENT">S4</acronym></td>
148 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
149 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
150 * <td><acronym title="AFTER_ROOT_ELEMENT">S5</acronym></td>
151 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
152 * </tr>
153 * <tr>
154 * <th>{@link #pi(String,String)}</th>
155 * <td><acronym title="BEFORE_DTD_DECLARATION">S1</acronym></td>
156 * <td><acronym title="BEFORE_DTD_DECLARATION">S1</acronym></td>
157 * <td><acronym title="BEFORE_ROOT_ELEMENT">S4</acronym></td>
158 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
159 * <td><acronym title="WITHIN_ELEMENT">S4</acronym></td>
160 * <td><acronym title="AFTER_ROOT_ELEMENT">S5</acronym></td>
161 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
162 * </tr>
163 * <tr>
164 * <th>{@link #endDocument()}</th>
165 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
166 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
167 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
168 * <td><acronym title="DOCUMENT_ENDED">S6</acronym></td>
169 * <td><acronym title="DOCUMENT_ENDED">S6</acronym></td>
170 * <td><acronym title="DOCUMENT_ENDED">S6</acronym></td>
171 * <td class="err"><acronym title="IllegalStateException">ISE</acronym></td>
172 * </tr>
173 * </table>
174 *
175 * <p>List of states as used in the table:
176 *
177 * <ul>
178 * <li>S0: {@link #BEFORE_XML_DECLARATION BEFORE_XML_DECLARATION}</li>
179 * <li>S1: {@link #BEFORE_DTD_DECLARATION BEFORE_DTD_DECLARATION}</li>
180 * <li>S2: {@link #BEFORE_ROOT_ELEMENT BEFORE_ROOT_ELEMENT}</li>
181 * <li>S3: {@link #START_TAG_OPEN START_TAG_OPEN}</li>
182 * <li>S4: {@link #WITHIN_ELEMENT WITHIN_ELEMENT}</li>
183 * <li>S5: {@link #AFTER_ROOT_ELEMENT AFTER_ROOT_ELEMENT}</li>
184 * <li>S6: {@link #DOCUMENT_ENDED DOCUMENT_ENDED}</li>
185 * </ul>
186 *
187 * @version $Revision: 1.9 $ $Date: 2005/09/12 08:40:02 $
188 * @author Ernst de Haan (<a href="mailto:wfe.dehaan@gmail.com">wfe.dehaan@gmail.com</a>)
189 *
190 * @since xmlenc 0.30
191 */
192 public interface XMLEventListener
193 extends XMLEventListenerStates {
194
195 /**
196 * Resets this XML event listener. The state will be set to
197 * {@link #UNINITIALIZED UNINITIALIZED}.
198 */
199 void reset();
200
201 /**
202 * Returns the current state of this outputter.
203 *
204 * @return
205 * the current state, cannot be <code>null</code>.
206 *
207 * @throws UnsupportedOperationException
208 * if this is not a stateful XML event listener.
209 */
210 XMLEventListenerState getState()
211 throws UnsupportedOperationException;
212
213 /**
214 * Sets the state of this XML event listener. Normally, it is not necessary
215 * to call this method and it should be used with great care.
216 *
217 * <p>Calling this method with {@link #UNINITIALIZED UNINITIALIZED} as
218 * the state is equivalent to calling {@link #reset()}.
219 *
220 * @param newState
221 * the new state, not <code>null</code>.
222 *
223 * @param newElementStack
224 * the new element stack, if <code>newState == {@link #START_TAG_OPEN START_TAG_OPEN}
225 * || newState == {@link #WITHIN_ELEMENT WITHIN_ELEMENT}</code> then it should be
226 * non-<code>null</code> and containing no <code>null</code> elements,
227 * otherwise it must be <code>null</code>.
228 *
229 * @throws IllegalArgumentException
230 * if <code>newState == null
231 * || (newState == {@link #START_TAG_OPEN START_TAG_OPEN} && newElementStack == null)
232 * || (newState == {@link #WITHIN_ELEMENT WITHIN_ELEMENT} && newElementStack == null)
233 * || (newState != {@link #START_TAG_OPEN START_TAG_OPEN} && newState != {@link #WITHIN_ELEMENT WITHIN_ELEMENT} && newElementStack != null)
234 * || newElementStack[<i>n</i>] == null</code> (where <code>0 <= <i>n</i> < newElementStack.length</code>).
235 */
236 void setState(XMLEventListenerState newState, String[] newElementStack)
237 throws IllegalArgumentException;
238
239 /**
240 * Notification of an XML declaration. No encoding is explicitly specified.
241 *
242 * @throws IllegalStateException
243 * if <code>getState() != BEFORE_XML_DECLARATION</code>.
244 *
245 * @throws IOException
246 * if an I/O error occurs; this will set the state to
247 * {@link #ERROR_STATE ERROR_STATE}.
248 */
249 void declaration() throws IllegalStateException, IOException;
250
251 /**
252 * Notification of a document type declaration.
253 *
254 * <p>An external subset can be specified using either a
255 * <em>system identifier</em> (alone), or using both a
256 * <em>public identifier</em> and a <em>system identifier</em>. It can
257 * never be specified using a <em>public identifier</em> alone.
258 *
259 * <p>For example, for XHTML 1.0 the public identifier is:
260 *
261 * <blockquote><code>-//W3C//DTD XHTML 1.0 Transitional//EN</code></blockquote>
262 *
263 * <p>while the system identifier is:
264 *
265 * <blockquote><code>http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd</code></blockquote>
266 *
267 * <p>The output is typically similar to this:
268 *
269 * <blockquote><code><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"></code></blockquote>
270 *
271 * or alternatively, if only the <em>system identifier</em> is specified:
272 *
273 * <blockquote><code><!DOCTYPE html SYSTEM "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"></code></blockquote>
274 *
275 * @param name
276 * the name of the document type, not <code>null</code>.
277 *
278 * @param publicID
279 * the public identifier, can be <code>null</code>.
280 *
281 * @param systemID
282 * the system identifier, can be <code>null</code>, but otherwise
283 * it should be a properly formatted URL, see
284 * <a href="http://www.w3.org/TR/2000/REC-xml-20001006#sec-external-ent">section 4.2.2 External Entities</a>
285 * in the XML 1.0 Specification.
286 *
287 * @throws IllegalStateException
288 * if <code>getState() != {@link #BEFORE_XML_DECLARATION BEFORE_XML_DECLARATION}&&
289 * getState() != {@link #BEFORE_DTD_DECLARATION BEFORE_DTD_DECLARATION}</code>.
290 *
291 * @throws IllegalArgumentException
292 * if <code>name == null ||
293 * (publicID != null && systemID == null)</code>.
294 *
295 * @throws IOException
296 * if an I/O error occurs; this will set the state to
297 * {@link #ERROR_STATE}.
298 */
299 void dtd(String name, String publicID, String systemID)
300 throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException;
301
302 /**
303 * Notification of an element start tag.
304 *
305 * @param type
306 * the type of the tag to start, not <code>null</code>.
307 *
308 * @throws IllegalStateException
309 * if <code>getState() != {@link #BEFORE_XML_DECLARATION BEFORE_XML_DECLARATION} &&
310 * getState() != {@link #BEFORE_DTD_DECLARATION BEFORE_DTD_DECLARATION} &&
311 * getState() != {@link #BEFORE_ROOT_ELEMENT BEFORE_ROOT_ELEMENT} &&
312 * getState() != {@link #START_TAG_OPEN START_TAG_OPEN} &&
313 * getState() != {@link #WITHIN_ELEMENT WITHIN_ELEMENT}</code>.
314 *
315 *
316 * @throws IllegalArgumentException
317 * if <code>type == null</code>.
318 *
319 * @throws IOException
320 * if an I/O error occurs; this will set the state to
321 * {@link #ERROR_STATE ERROR_STATE}.
322 */
323 void startTag(String type)
324 throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException;
325
326 /**
327 * Adds an attribute to the current element. There must currently be an
328 * open element.
329 *
330 * <p>The attribute value is surrounded by single quotes.
331 *
332 * @param name
333 * the name of the attribute, not <code>null</code>.
334 *
335 * @param value
336 * the value of the attribute, not <code>null</code>.
337 *
338 * @throws IllegalStateException
339 * if <code>getState() != {@link #START_TAG_OPEN}</code>.
340 *
341 * @throws IllegalArgumentException
342 * if <code>name == null || value == null</code>.
343 *
344 * @throws IOException
345 * if an I/O error occurs; this will set the state to
346 * {@link #ERROR_STATE}.
347 */
348 void attribute(String name, String value)
349 throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException;
350
351 /**
352 * Notification of an element end tag.
353 *
354 * @throws IllegalStateException
355 * if <code>getState() != START_TAG_OPEN &&
356 * getState() != WITHIN_ELEMENT</code>
357 *
358 * @throws IOException
359 * if an I/O error occurs; this will set the state to
360 * {@link #ERROR_STATE}.
361 */
362 void endTag()
363 throws IllegalStateException, IOException;
364
365 /**
366 * Notification of a PCDATA section (as a <code>String</code>).
367 *
368 * @param text
369 * the PCDATA section contents, not <code>null</code>.
370 *
371 * @throws IllegalStateException
372 * if <code>getState() != START_TAG_OPEN &&
373 * getState() != WITHIN_ELEMENT</code>
374 *
375 * @throws IllegalArgumentException
376 * if <code>text == null</code>.
377 *
378 * @throws InvalidXMLException
379 * if the specified text contains an invalid character.
380 *
381 * @throws IOException
382 * if an I/O error occurs; this will set the state to
383 * {@link #ERROR_STATE}.
384 */
385 void pcdata(String text)
386 throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException;
387
388 /**
389 * Notification of a PCDATA section (as a <code>char</code> array).
390 *
391 * @param ch
392 * the character array containing the PCDATA section contents, not
393 * <code>null</code>.
394 *
395 * @param start
396 * the start index in the array, must be >= 0 and it must be <
397 * <code>ch.length</code>.
398 *
399 * @param length
400 * the number of characters to read from the array, must be > 0.
401 *
402 * @throws IllegalStateException
403 * if <code>getState() != START_TAG_OPEN &&
404 * getState() != WITHIN_ELEMENT</code>
405 *
406 * @throws IllegalArgumentException
407 * if <code>ch == null
408 * || start < 0
409 * || start >= ch.length
410 * || length < 0</code>.
411 *
412 * @throws IndexOutOfBoundsException
413 * if <code>start + length > ch.length</code>.
414 *
415 * @throws InvalidXMLException
416 * if the specified text contains an invalid character.
417 *
418 * @throws IOException
419 * if an I/O error occurs; this will set the state to
420 * {@link #ERROR_STATE}.
421 */
422 void pcdata(char[] ch, int start, int length)
423 throws IllegalStateException, IllegalArgumentException, IndexOutOfBoundsException, InvalidXMLException, IOException;
424
425 /**
426 * Notification of a CDATA section.
427 *
428 * <p>A CDATA section can contain any string, except
429 * <code>"]]>"</code>. This will, however, not be checked by this
430 * method.
431 *
432 * <p>Left angle brackets and ampersands will be output in their literal
433 * form; they need not (and cannot) be escaped using
434 * <code>"&lt;"</code> and <code>"&amp;"</code>.
435 *
436 * <p>If the specified string is empty (i.e.
437 * <code>"".equals(text)</code>, then nothing will be output.
438 *
439 * <p>If the specified string contains characters that cannot be printed
440 * in this encoding, then the result is undefined.
441 *
442 * @param text
443 * the contents of the CDATA section, not <code>null</code>.
444 *
445 * @throws IllegalStateException
446 * if <code>getState() != START_TAG_OPEN &&
447 * getState() != WITHIN_ELEMENT</code>
448 *
449 * @throws IllegalArgumentException
450 * if <code>text == null</code>.
451 *
452 * @throws InvalidXMLException
453 * if the specified text contains an invalid character.
454 *
455 * @throws IOException
456 * if an I/O error occurs; this will set the state to
457 * {@link #ERROR_STATE}.
458 */
459 void cdata(String text)
460 throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException;
461
462 /**
463 * Notification of ignorable whitespace (as a <code>String</code>).
464 * Ignorable whitespace can be found anywhere in an XML document,
465 * except above the XML declaration.
466 *
467 * <p>This method does not check if the string actually contains
468 * whitespace.
469 *
470 * <p>If the state equals {@link #BEFORE_XML_DECLARATION}, then it will be set to
471 * {@link #BEFORE_DTD_DECLARATION}, otherwise if the state is
472 * {@link #START_TAG_OPEN} then it will be set to {@link #WITHIN_ELEMENT},
473 * otherwise the state will not be changed.
474 *
475 * @param whitespace
476 * the ignorable whitespace to be written, not <code>null</code>.
477 *
478 * @throws IllegalStateException
479 * if <code>getState() == ERROR_STATE</code>.
480 *
481 * @throws IllegalArgumentException
482 * if <code>whitespace == null</code>.
483 *
484 * @throws InvalidXMLException
485 * if the specified text contains an invalid character.
486 *
487 * @throws IOException
488 * if an I/O error occurs; this will set the state to
489 * {@link #ERROR_STATE}.
490 */
491 void whitespace(String whitespace)
492 throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException;
493
494 /**
495 * Notification of ignorable whitespace (as a <code>String</code>).
496 * Ignorable whitespace can be found anywhere in an XML document,
497 * except above the XML declaration.
498 *
499 * <p>This method does not check if the string actually contains
500 * whitespace.
501 *
502 * <p>If the state equals {@link #BEFORE_XML_DECLARATION}, then it will be set to
503 * {@link #BEFORE_DTD_DECLARATION}, otherwise if the state is
504 * {@link #START_TAG_OPEN} then it will be set to {@link #WITHIN_ELEMENT},
505 * otherwise the state will not be changed.
506 *
507 * @param ch
508 * the character array containing the text to be written, not
509 * <code>null</code>.
510 *
511 * @param start
512 * the start index in the array, must be >= 0 and it must be <
513 * <code>ch.length</code>.
514 *
515 * @param length
516 * the number of characters to read from the array, must be > 0.
517 *
518 * @throws IllegalStateException
519 * if <code>getState() == ERROR_STATE</code>.
520 *
521 * @throws IllegalArgumentException
522 * if <code>ch == null
523 * || start < 0
524 * || start >= ch.length
525 * || length < 0</code>.
526 *
527 * @throws IndexOutOfBoundsException
528 * if <code>start + length > ch.length</code>.
529 *
530 * @throws InvalidXMLException
531 * if the specified text contains an invalid character.
532 *
533 * @throws IOException
534 * if an I/O error occurs; this will set the state to
535 * {@link #ERROR_STATE}.
536 */
537 void whitespace(char[] ch, int start, int length)
538 throws IllegalStateException, IllegalArgumentException, IndexOutOfBoundsException, InvalidXMLException, IOException;
539
540 /**
541 * Notification of a comment. The comment should not contain the string
542 * <code>"--"</code>.
543 *
544 * <p>If the state equals {@link #BEFORE_XML_DECLARATION}, then it will be set to
545 * {@link #BEFORE_DTD_DECLARATION}, otherwise if the state is
546 * {@link #START_TAG_OPEN} then it will be set to {@link #WITHIN_ELEMENT},
547 * otherwise the state will not be changed.
548 *
549 * @param text
550 * the text for the comment be written, not <code>null</code>.
551 *
552 * @throws IllegalStateException
553 * if <code>getState() == ERROR_STATE</code>.
554 *
555 * @throws IllegalArgumentException
556 * if <code>text == null</code>.
557 *
558 * @throws InvalidXMLException
559 * if the specified text contains an invalid character.
560 *
561 * @throws IOException
562 * if an I/O error occurs; this will set the state to
563 * {@link #ERROR_STATE}.
564 */
565 void comment(String text)
566 throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException;
567
568 /**
569 * Notification of a processing instruction. A target and an optional
570 * instruction should be specified.
571 *
572 * <p>A processing instruction can appear above and below the root
573 * element, and between elements. It cannot appear inside an element start
574 * or end tag, nor inside a comment. Processing instructions cannot be
575 * nested.
576 *
577 * <p>If the state equals {@link #BEFORE_XML_DECLARATION}, then it will be set to
578 * {@link #BEFORE_DTD_DECLARATION}, otherwise the state will not be
579 * changed.
580 *
581 * @param target
582 * an identification of the application at which the instruction is
583 * targeted, not <code>null</code>.
584 *
585 * @param instruction
586 * the instruction, can be <code>null</code>, which is equivalent to an
587 * empty string.
588 *
589 * @throws IllegalStateException
590 * if <code>getState() == ERROR_STATE</code>.
591 *
592 * @throws IllegalArgumentException
593 * if <code>target == null</code>.
594 *
595 * @throws InvalidXMLException
596 * if the specified text contains an invalid character.
597 *
598 * @throws IOException
599 * if an I/O error occurs; this will set the state to
600 * {@link #ERROR_STATE}.
601 */
602 void pi(String target, String instruction)
603 throws IllegalStateException, IllegalArgumentException, InvalidXMLException, IOException;
604
605 /**
606 * Notification of the end of the document. After calling this method, none
607 * of the other notification methods can be called until {@link #reset()}
608 * is called.
609 *
610 * @throws IllegalStateException
611 * if <code>getState() == UNINITIALIZED
612 * || getState() == DOCUMENT_ENDED</code>.
613 *
614 * @throws IOException
615 * if an I/O error occurs; this will set the state to
616 * {@link #ERROR_STATE}.
617 */
618 void endDocument()
619 throws IllegalStateException, IOException;
620 }