lib/classpath/external/sax/org/xml/sax/ContentHandler.java

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