libjava/org/xml/sax/ContentHandler.java

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