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