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