XMLEventListener


1   /*
2    * $Id: XMLEventListener.java,v 1.8 2003/08/05 11:41:48 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.8 $ $Date: 2003/08/05 11:41:48 $
188  * @author Ernst de Haan (<a HREF="mailto:znerd@FreeBSD.org">znerd@FreeBSD.org</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} &amp;&amp; newElementStack == null)
232     *          || (newState == {@link #WITHIN_ELEMENT WITHIN_ELEMENT} &amp;&amp; newElementStack == null)
233     *          || (newState != {@link #START_TAG_OPEN START_TAG_OPEN} &amp;&amp; newState != {@link #WITHIN_ELEMENT WITHIN_ELEMENT} &amp;&amp; newElementStack != null)
234     *          || newElementStack[<i>n</i>] == null</code> (where <code>0 &lt;= <i>n</i> &lt; 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>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"&gt;</code></blockquote>
270     *
271     * or alternatively, if only the <em>system identifier</em> is specified:
272     *
273     * <blockquote><code>&lt;!DOCTYPE html SYSTEM "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"&gt;</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}&amp;&amp;
289     *             getState() != {@link #BEFORE_DTD_DECLARATION BEFORE_DTD_DECLARATION}</code>.
290     *
291     * @throws IllegalArgumentException
292     *    if <code>name == null ||
293     *          (publicID != null &amp;&amp; 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} &amp;&amp;
310     *             getState() != {@link #BEFORE_DTD_DECLARATION BEFORE_DTD_DECLARATION} &amp;&amp;
311     *             getState() != {@link #BEFORE_ROOT_ELEMENT    BEFORE_ROOT_ELEMENT} &amp;&amp;
312     *             getState() != {@link #START_TAG_OPEN         START_TAG_OPEN} &amp;&amp;
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 &amp;&amp;
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 &amp;&amp;
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 &gt;= 0 and it must be &lt;
397     *    <code>ch.length</code>.
398     *
399     * @param length
400     *    the number of characters to read from the array, must be &gt; 0.
401     *
402     * @throws IllegalStateException
403     *    if <code>getState() != START_TAG_OPEN &amp;&amp;
404     *             getState() != WITHIN_ELEMENT</code>
405     *
406     * @throws IllegalArgumentException
407     *    if <code>ch     ==    null
408     *          || start  &lt;  0
409     *          || start  &gt;= ch.length
410     *          || length &lt;  0</code>.
411     *
412     * @throws IndexOutOfBoundsException
413     *    if <code>start + length &gt; 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>"]]&gt;"</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>"&amp;lt;"</code> and <code>"&amp;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 &amp;&amp;
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 &gt;= 0 and it must be &lt;
513     *    <code>ch.length</code>.
514     *
515     * @param length
516     *    the number of characters to read from the array, must be &gt; 0.
517     *
518     * @throws IllegalStateException
519     *    if <code>getState() == ERROR_STATE</code>.
520     *
521     * @throws IllegalArgumentException
522     *    if <code>ch     ==    null
523     *          || start  &lt;  0
524     *          || start  &gt;= ch.length
525     *          || length &lt;  0</code>.
526     *
527     * @throws IndexOutOfBoundsException
528     *    if <code>start + length &gt; 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 }
621
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags