| Frames | No Frames |
1: // SAX document handler. 2: // http://www.saxproject.org 3: // No warranty; no copyright -- use this as you will. 4: // $Id: DocumentHandler.java,v 1.1 2004/12/23 22:38:42 mark Exp $ 5: 6: package org.xml.sax; 7: 8: /** 9: * Receive notification of general document events. 10: * 11: * <blockquote> 12: * <em>This module, both source code and documentation, is in the 13: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 14: * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> 15: * for further information. 16: * </blockquote> 17: * 18: * <p>This was the main event-handling interface for SAX1; in 19: * SAX2, it has been replaced by {@link org.xml.sax.ContentHandler 20: * ContentHandler}, which provides Namespace support and reporting 21: * of skipped entities. This interface is included in SAX2 only 22: * to support legacy SAX1 applications.</p> 23: * 24: * <p>The order of events in this interface is very important, and 25: * mirrors the order of information in the document itself. For 26: * example, all of an element's content (character data, processing 27: * instructions, and/or subelements) will appear, in order, between 28: * the startElement event and the corresponding endElement event.</p> 29: * 30: * <p>Application writers who do not want to implement the entire 31: * interface can derive a class from HandlerBase, which implements 32: * the default functionality; parser writers can instantiate 33: * HandlerBase to obtain a default handler. The application can find 34: * the location of any document event using the Locator interface 35: * supplied by the Parser through the setDocumentLocator method.</p> 36: * 37: * @deprecated This interface has been replaced by the SAX2 38: * {@link org.xml.sax.ContentHandler ContentHandler} 39: * interface, which includes Namespace support. 40: * @since SAX 1.0 41: * @author David Megginson 42: * @version 2.0.1 (sax2r2) 43: * @see org.xml.sax.Parser#setDocumentHandler 44: * @see org.xml.sax.Locator 45: * @see org.xml.sax.HandlerBase 46: */ 47: public interface DocumentHandler { 48: 49: 50: /** 51: * Receive an object for locating the origin of SAX document events. 52: * 53: * <p>SAX parsers are strongly encouraged (though not absolutely 54: * required) to supply a locator: if it does so, it must supply 55: * the locator to the application by invoking this method before 56: * invoking any of the other methods in the DocumentHandler 57: * interface.</p> 58: * 59: * <p>The locator allows the application to determine the end 60: * position of any document-related event, even if the parser is 61: * not reporting an error. Typically, the application will 62: * use this information for reporting its own errors (such as 63: * character content that does not match an application's 64: * business rules). The information returned by the locator 65: * is probably not sufficient for use with a search engine.</p> 66: * 67: * <p>Note that the locator will return correct information only 68: * during the invocation of the events in this interface. The 69: * application should not attempt to use it at any other time.</p> 70: * 71: * @param locator An object that can return the location of 72: * any SAX document event. 73: * @see org.xml.sax.Locator 74: */ 75: public abstract void setDocumentLocator (Locator locator); 76: 77: 78: /** 79: * Receive notification of the beginning of a document. 80: * 81: * <p>The SAX parser will invoke this method only once, before any 82: * other methods in this interface or in DTDHandler (except for 83: * setDocumentLocator).</p> 84: * 85: * @exception org.xml.sax.SAXException Any SAX exception, possibly 86: * wrapping another exception. 87: */ 88: public abstract void startDocument () 89: throws SAXException; 90: 91: 92: /** 93: * Receive notification of the end of a document. 94: * 95: * <p>The SAX parser will invoke this method only once, and it will 96: * be the last method invoked during the parse. The parser shall 97: * not invoke this method until it has either abandoned parsing 98: * (because of an unrecoverable error) or reached the end of 99: * input.</p> 100: * 101: * @exception org.xml.sax.SAXException Any SAX exception, possibly 102: * wrapping another exception. 103: */ 104: public abstract void endDocument () 105: throws SAXException; 106: 107: 108: /** 109: * Receive notification of the beginning of an element. 110: * 111: * <p>The Parser will invoke this method at the beginning of every 112: * element in the XML document; there will be a corresponding 113: * endElement() event for every startElement() event (even when the 114: * element is empty). All of the element's content will be 115: * reported, in order, before the corresponding endElement() 116: * event.</p> 117: * 118: * <p>If the element name has a namespace prefix, the prefix will 119: * still be attached. Note that the attribute list provided will 120: * contain only attributes with explicit values (specified or 121: * defaulted): #IMPLIED attributes will be omitted.</p> 122: * 123: * @param name The element type name. 124: * @param atts The attributes attached to the element, if any. 125: * @exception org.xml.sax.SAXException Any SAX exception, possibly 126: * wrapping another exception. 127: * @see #endElement 128: * @see org.xml.sax.AttributeList 129: */ 130: public abstract void startElement (String name, AttributeList atts) 131: throws SAXException; 132: 133: 134: /** 135: * Receive notification of the end of an element. 136: * 137: * <p>The SAX parser will invoke this method at the end of every 138: * element in the XML document; there will be a corresponding 139: * startElement() event for every endElement() event (even when the 140: * element is empty).</p> 141: * 142: * <p>If the element name has a namespace prefix, the prefix will 143: * still be attached to the name.</p> 144: * 145: * @param name The element type name 146: * @exception org.xml.sax.SAXException Any SAX exception, possibly 147: * wrapping another exception. 148: */ 149: public abstract void endElement (String name) 150: throws SAXException; 151: 152: 153: /** 154: * Receive notification of character data. 155: * 156: * <p>The Parser will call this method to report each chunk of 157: * character data. SAX parsers may return all contiguous character 158: * data in a single chunk, or they may split it into several 159: * chunks; however, all of the characters in any single event 160: * must come from the same external entity, so that the Locator 161: * provides useful information.</p> 162: * 163: * <p>The application must not attempt to read from the array 164: * outside of the specified range.</p> 165: * 166: * <p>Note that some parsers will report whitespace using the 167: * ignorableWhitespace() method rather than this one (validating 168: * parsers must do so).</p> 169: * 170: * @param ch The characters from the XML document. 171: * @param start The start position in the array. 172: * @param length The number of characters to read from the array. 173: * @exception org.xml.sax.SAXException Any SAX exception, possibly 174: * wrapping another exception. 175: * @see #ignorableWhitespace 176: * @see org.xml.sax.Locator 177: */ 178: public abstract void characters (char ch[], int start, int length) 179: throws SAXException; 180: 181: 182: /** 183: * Receive notification of ignorable whitespace in element content. 184: * 185: * <p>Validating Parsers must use this method to report each chunk 186: * of ignorable whitespace (see the W3C XML 1.0 recommendation, 187: * section 2.10): non-validating parsers may also use this method 188: * if they are capable of parsing and using content models.</p> 189: * 190: * <p>SAX parsers may return all contiguous whitespace in a single 191: * chunk, or they may split it into several chunks; however, all of 192: * the characters in any single event must come from the same 193: * external entity, so that the Locator provides useful 194: * information.</p> 195: * 196: * <p>The application must not attempt to read from the array 197: * outside of the specified range.</p> 198: * 199: * @param ch The characters from the XML document. 200: * @param start The start position in the array. 201: * @param length The number of characters to read from the array. 202: * @exception org.xml.sax.SAXException Any SAX exception, possibly 203: * wrapping another exception. 204: * @see #characters 205: */ 206: public abstract void ignorableWhitespace (char ch[], int start, int length) 207: throws SAXException; 208: 209: 210: /** 211: * Receive notification of a processing instruction. 212: * 213: * <p>The Parser will invoke this method once for each processing 214: * instruction found: note that processing instructions may occur 215: * before or after the main document element.</p> 216: * 217: * <p>A SAX parser should never report an XML declaration (XML 1.0, 218: * section 2.8) or a text declaration (XML 1.0, section 4.3.1) 219: * using this method.</p> 220: * 221: * @param target The processing instruction target. 222: * @param data The processing instruction data, or null if 223: * none was supplied. 224: * @exception org.xml.sax.SAXException Any SAX exception, possibly 225: * wrapping another exception. 226: */ 227: public abstract void processingInstruction (String target, String data) 228: throws SAXException; 229: 230: } 231: 232: // end of DocumentHandler.java