| Frames | No Frames |
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