View Javadoc

1   // ContentHandler.java - handle main document content.
2   // http://www.saxproject.org
3   // Written by David Megginson
4   // NO WARRANTY!  This class is in the public domain.
5   // $Id: ContentHandler.java,v 1.5 2004/03/19 20:17:54 maartenc Exp $
6   
7   package org.xml.sax;
8   
9   
10  /***
11   * Receive notification of the logical content of a document.
12   *
13   * <blockquote>
14   * <em>This module, both source code and documentation, is in the
15   * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
16   * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
17   * for further information.
18   * </blockquote>
19   *
20   * <p>This is the main interface that most SAX applications
21   * implement: if the application needs to be informed of basic parsing 
22   * events, it implements this interface and registers an instance with 
23   * the SAX parser using the {@link org.xml.sax.XMLReader#setContentHandler 
24   * setContentHandler} method.  The parser uses the instance to report 
25   * basic document-related events like the start and end of elements 
26   * and character data.</p>
27   *
28   * <p>The order of events in this interface is very important, and
29   * mirrors the order of information in the document itself.  For
30   * example, all of an element's content (character data, processing
31   * instructions, and/or subelements) will appear, in order, between
32   * the startElement event and the corresponding endElement event.</p>
33   *
34   * <p>This interface is similar to the now-deprecated SAX 1.0
35   * DocumentHandler interface, but it adds support for Namespaces
36   * and for reporting skipped entities (in non-validating XML
37   * processors).</p>
38   *
39   * <p>Implementors should note that there is also a Java class
40   * {@link java.net.ContentHandler ContentHandler} in the java.net
41   * package; that means that it's probably a bad idea to do</p>
42   *
43   * <blockquote>
44   * import java.net.*;
45   * import org.xml.sax.*;
46   * </blockquote>
47   *
48   * <p>In fact, "import ...*" is usually a sign of sloppy programming
49   * anyway, so the user should consider this a feature rather than a
50   * bug.</p>
51   *
52   * @since SAX 2.0
53   * @author David Megginson
54   * @version 2.0.1+ (sax2r3pre1)
55   * @see org.xml.sax.XMLReader
56   * @see org.xml.sax.DTDHandler
57   * @see org.xml.sax.ErrorHandler
58   */
59  public interface ContentHandler
60  {
61  
62      /***
63       * Receive an object for locating the origin of SAX document events.
64       *
65       * <p>SAX parsers are strongly encouraged (though not absolutely
66       * required) to supply a locator: if it does so, it must supply
67       * the locator to the application by invoking this method before
68       * invoking any of the other methods in the ContentHandler
69       * interface.</p>
70       *
71       * <p>The locator allows the application to determine the end
72       * position of any document-related event, even if the parser is
73       * not reporting an error.  Typically, the application will
74       * use this information for reporting its own errors (such as
75       * character content that does not match an application's
76       * business rules).  The information returned by the locator
77       * is probably not sufficient for use with a search engine.</p>
78       *
79       * <p>Note that the locator will return correct information only
80       * during the invocation SAX event callbacks after
81       * {@link #startDocument startDocument} returns and before
82       * {@link #endDocument endDocument} is called.  The
83       * application should not attempt to use it at any other time.</p>
84       *
85       * @param locator An object that can return the location of
86       *                any SAX document event.
87       * @see org.xml.sax.Locator
88       */
89      public void setDocumentLocator (Locator locator);
90  
91  
92      /***
93       * Receive notification of the beginning of a document.
94       *
95       * <p>The SAX parser will invoke this method only once, before any
96       * other event callbacks (except for {@link #setDocumentLocator 
97       * setDocumentLocator}).</p>
98       *
99       * @exception org.xml.sax.SAXException Any SAX exception, possibly
100      *            wrapping another exception.
101      * @see #endDocument
102      */
103     public void startDocument ()
104 	throws SAXException;
105 
106 
107     /***
108      * Receive notification of the end of a document.
109      *
110      * <p><strong>There is an apparent contradiction between the
111      * documentation for this method and the documentation for {@link
112      * org.xml.sax.ErrorHandler#fatalError}.  Until this ambiguity is
113      * resolved in a future major release, clients should make no
114      * assumptions about whether endDocument() will or will not be
115      * invoked when the parser has reported a fatalError() or thrown
116      * an exception.</strong></p>
117      *
118      * <p>The SAX parser will invoke this method only once, and it will
119      * be the last method invoked during the parse.  The parser shall
120      * not invoke this method until it has either abandoned parsing
121      * (because of an unrecoverable error) or reached the end of
122      * input.</p>
123      *
124      * @exception org.xml.sax.SAXException Any SAX exception, possibly
125      *            wrapping another exception.
126      * @see #startDocument
127      */
128     public void endDocument()
129 	throws SAXException;
130 
131 
132     /***
133      * Begin the scope of a prefix-URI Namespace mapping.
134      *
135      * <p>The information from this event is not necessary for
136      * normal Namespace processing: the SAX XML reader will 
137      * automatically replace prefixes for element and attribute
138      * names when the <code>http://xml.org/sax/features/namespaces</code>
139      * feature is <var>true</var> (the default).</p>
140      *
141      * <p>There are cases, however, when applications need to
142      * use prefixes in character data or in attribute values,
143      * where they cannot safely be expanded automatically; the
144      * start/endPrefixMapping event supplies the information
145      * to the application to expand prefixes in those contexts
146      * itself, if necessary.</p>
147      *
148      * <p>Note that start/endPrefixMapping events are not
149      * guaranteed to be properly nested relative to each other:
150      * all startPrefixMapping events will occur immediately before the
151      * corresponding {@link #startElement startElement} event, 
152      * and all {@link #endPrefixMapping endPrefixMapping}
153      * events will occur immediately after the corresponding
154      * {@link #endElement endElement} event,
155      * but their order is not otherwise 
156      * guaranteed.</p>
157      *
158      * <p>There should never be start/endPrefixMapping events for the
159      * "xml" prefix, since it is predeclared and immutable.</p>
160      *
161      * @param prefix The Namespace prefix being declared.
162      *	An empty string is used for the default element namespace,
163      *	which has no prefix.
164      * @param uri The Namespace URI the prefix is mapped to.
165      * @exception org.xml.sax.SAXException The client may throw
166      *            an exception during processing.
167      * @see #endPrefixMapping
168      * @see #startElement
169      */
170     public void startPrefixMapping (String prefix, String uri)
171 	throws SAXException;
172 
173 
174     /***
175      * End the scope of a prefix-URI mapping.
176      *
177      * <p>See {@link #startPrefixMapping startPrefixMapping} for 
178      * details.  These events will always occur immediately after the
179      * corresponding {@link #endElement endElement} event, but the order of 
180      * {@link #endPrefixMapping endPrefixMapping} events is not otherwise
181      * guaranteed.</p>
182      *
183      * @param prefix The prefix that was being mapped.
184      *	This is the empty string when a default mapping scope ends.
185      * @exception org.xml.sax.SAXException The client may throw
186      *            an exception during processing.
187      * @see #startPrefixMapping
188      * @see #endElement
189      */
190     public void endPrefixMapping (String prefix)
191 	throws SAXException;
192 
193 
194     /***
195      * Receive notification of the beginning of an element.
196      *
197      * <p>The Parser will invoke this method at the beginning of every
198      * element in the XML document; there will be a corresponding
199      * {@link #endElement endElement} event for every startElement event
200      * (even when the element is empty). All of the element's content will be
201      * reported, in order, before the corresponding endElement
202      * event.</p>
203      *
204      * <p>This event allows up to three name components for each
205      * element:</p>
206      *
207      * <ol>
208      * <li>the Namespace URI;</li>
209      * <li>the local name; and</li>
210      * <li>the qualified (prefixed) name.</li>
211      * </ol>
212      *
213      * <p>Any or all of these may be provided, depending on the
214      * values of the <var>http://xml.org/sax/features/namespaces</var>
215      * and the <var>http://xml.org/sax/features/namespace-prefixes</var>
216      * properties:</p>
217      *
218      * <ul>
219      * <li>the Namespace URI and local name are required when 
220      * the namespaces property is <var>true</var> (the default), and are
221      * optional when the namespaces property is <var>false</var> (if one is
222      * specified, both must be);</li>
223      * <li>the qualified name is required when the namespace-prefixes property
224      * is <var>true</var>, and is optional when the namespace-prefixes property
225      * is <var>false</var> (the default).</li>
226      * </ul>
227      *
228      * <p>Note that the attribute list provided will contain only
229      * attributes with explicit values (specified or defaulted):
230      * #IMPLIED attributes will be omitted.  The attribute list
231      * will contain attributes used for Namespace declarations
232      * (xmlns* attributes) only if the
233      * <code>http://xml.org/sax/features/namespace-prefixes</code>
234      * property is true (it is false by default, and support for a 
235      * true value is optional).</p>
236      *
237      * <p>Like {@link #characters characters()}, attribute values may have
238      * characters that need more than one <code>char</code> value.  </p>
239      *
240      * @param uri The Namespace URI, or the empty string if the
241      *        element has no Namespace URI or if Namespace
242      *        processing is not being performed.
243      * @param localName The local name (without prefix), or the
244      *        empty string if Namespace processing is not being
245      *        performed.
246      * @param qName The qualified name (with prefix), or the
247      *        empty string if qualified names are not available.
248      * @param atts The attributes attached to the element.  If
249      *        there are no attributes, it shall be an empty
250      *        Attributes object.
251      * @exception org.xml.sax.SAXException Any SAX exception, possibly
252      *            wrapping another exception.
253      * @see #endElement
254      * @see org.xml.sax.Attributes
255      */
256     public void startElement (String uri, String localName,
257 			      String qName, Attributes atts)
258 	throws SAXException;
259 
260 
261     /***
262      * Receive notification of the end of an element.
263      *
264      * <p>The SAX parser will invoke this method at the end of every
265      * element in the XML document; there will be a corresponding
266      * {@link #startElement startElement} event for every endElement 
267      * event (even when the element is empty).</p>
268      *
269      * <p>For information on the names, see startElement.</p>
270      *
271      * @param uri The Namespace URI, or the empty string if the
272      *        element has no Namespace URI or if Namespace
273      *        processing is not being performed.
274      * @param localName The local name (without prefix), or the
275      *        empty string if Namespace processing is not being
276      *        performed.
277      * @param qName The qualified XML name (with prefix), or the
278      *        empty string if qualified names are not available.
279      * @exception org.xml.sax.SAXException Any SAX exception, possibly
280      *            wrapping another exception.
281      */
282     public void endElement (String uri, String localName,
283 			    String qName)
284 	throws SAXException;
285 
286 
287     /***
288      * Receive notification of character data.
289      *
290      * <p>The Parser will call this method to report each chunk of
291      * character data.  SAX parsers may return all contiguous character
292      * data in a single chunk, or they may split it into several
293      * chunks; however, all of the characters in any single event
294      * must come from the same external entity so that the Locator
295      * provides useful information.</p>
296      *
297      * <p>The application must not attempt to read from the array
298      * outside of the specified range.</p>
299      *
300      * <p>Individual characters may consist of more than one Java
301      * <code>char</code> value.  There are two important cases where this
302      * happens, because characters can't be represented in just sixteen bits.
303      * In one case, characters are represented in a <em>Surrogate Pair</em>,
304      * using two special Unicode values. Such characters are in the so-called
305      * "Astral Planes", with a code point above U+FFFF.  A second case involves
306      * composite characters, such as a base character combining with one or
307      * more accent characters. </p>
308      *
309      * <p> Your code should not assume that algorithms using
310      * <code>char</code>-at-a-time idioms will be working in character
311      * units; in some cases they will split characters.  This is relevant
312      * wherever XML permits arbitrary characters, such as attribute values,
313      * processing instruction data, and comments as well as in data reported
314      * from this method.  It's also generally relevant whenever Java code
315      * manipulates internationalized text; the issue isn't unique to XML.</p>
316      *
317      * <p>Note that some parsers will report whitespace in element
318      * content using the {@link #ignorableWhitespace ignorableWhitespace}
319      * method rather than this one (validating parsers <em>must</em> 
320      * do so).</p>
321      *
322      * @param ch The characters from the XML document.
323      * @param start The start position in the array.
324      * @param length The number of characters to read from the array.
325      * @exception org.xml.sax.SAXException Any SAX exception, possibly
326      *            wrapping another exception.
327      * @see #ignorableWhitespace 
328      * @see org.xml.sax.Locator
329      */
330     public void characters (char ch[], int start, int length)
331 	throws SAXException;
332 
333 
334     /***
335      * Receive notification of ignorable whitespace in element content.
336      *
337      * <p>Validating Parsers must use this method to report each chunk
338      * of whitespace in element content (see the W3C XML 1.0
339      * recommendation, section 2.10): non-validating parsers may also
340      * use this method if they are capable of parsing and using
341      * content models.</p>
342      *
343      * <p>SAX parsers may return all contiguous whitespace in a single
344      * chunk, or they may split it into several chunks; however, all of
345      * the characters in any single event must come from the same
346      * external entity, so that the Locator provides useful
347      * information.</p>
348      *
349      * <p>The application must not attempt to read from the array
350      * outside of the specified range.</p>
351      *
352      * @param ch The characters from the XML document.
353      * @param start The start position in the array.
354      * @param length The number of characters to read from the array.
355      * @exception org.xml.sax.SAXException Any SAX exception, possibly
356      *            wrapping another exception.
357      * @see #characters
358      */
359     public void ignorableWhitespace (char ch[], int start, int length)
360 	throws SAXException;
361 
362 
363     /***
364      * Receive notification of a processing instruction.
365      *
366      * <p>The Parser will invoke this method once for each processing
367      * instruction found: note that processing instructions may occur
368      * before or after the main document element.</p>
369      *
370      * <p>A SAX parser must never report an XML declaration (XML 1.0,
371      * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
372      * using this method.</p>
373      *
374      * <p>Like {@link #characters characters()}, processing instruction
375      * data may have characters that need more than one <code>char</code>
376      * value. </p>
377      *
378      * @param target The processing instruction target.
379      * @param data The processing instruction data, or null if
380      *        none was supplied.  The data does not include any
381      *        whitespace separating it from the target.
382      * @exception org.xml.sax.SAXException Any SAX exception, possibly
383      *            wrapping another exception.
384      */
385     public void processingInstruction (String target, String data)
386 	throws SAXException;
387 
388 
389     /***
390      * Receive notification of a skipped entity.
391      * This is not called for entity references within markup constructs
392      * such as element start tags or markup declarations.  (The XML
393      * recommendation requires reporting skipped external entities.
394      * SAX also reports internal entity expansion/non-expansion, except
395      * within markup constructs.)
396      *
397      * <p>The Parser will invoke this method each time the entity is
398      * skipped.  Non-validating processors may skip entities if they
399      * have not seen the declarations (because, for example, the
400      * entity was declared in an external DTD subset).  All processors
401      * may skip external entities, depending on the values of the
402      * <code>http://xml.org/sax/features/external-general-entities</code>
403      * and the
404      * <code>http://xml.org/sax/features/external-parameter-entities</code>
405      * properties.</p>
406      *
407      * @param name The name of the skipped entity.  If it is a 
408      *        parameter entity, the name will begin with '%', and if
409      *        it is the external DTD subset, it will be the string
410      *        "[dtd]".
411      * @exception org.xml.sax.SAXException Any SAX exception, possibly
412      *            wrapping another exception.
413      */
414     public void skippedEntity (String name)
415 	throws SAXException;
416 }
417 
418 // end of ContentHandler.java