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.6 2002/01/30 21:13:43 dbrownell 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 @Deprecated 48 public interface DocumentHandler { 49 50 51 /** 52 * Receive an object for locating the origin of SAX document events. 53 * 54 * <p>SAX parsers are strongly encouraged (though not absolutely 55 * required) to supply a locator: if it does so, it must supply 56 * the locator to the application by invoking this method before 57 * invoking any of the other methods in the DocumentHandler 58 * interface.</p> 59 * 60 * <p>The locator allows the application to determine the end 61 * position of any document-related event, even if the parser is 62 * not reporting an error. Typically, the application will 63 * use this information for reporting its own errors (such as 64 * character content that does not match an application's 65 * business rules). The information returned by the locator 66 * is probably not sufficient for use with a search engine.</p> 67 * 68 * <p>Note that the locator will return correct information only 69 * during the invocation of the events in this interface. The 70 * application should not attempt to use it at any other time.</p> 71 * 72 * @param locator An object that can return the location of 73 * any SAX document event. 74 * @see org.xml.sax.Locator 75 */ 76 public abstract void setDocumentLocator (Locator locator); 77 78 79 /** 80 * Receive notification of the beginning of a document. 81 * 82 * <p>The SAX parser will invoke this method only once, before any 83 * other methods in this interface or in DTDHandler (except for 84 * setDocumentLocator).</p> 85 * 86 * @exception org.xml.sax.SAXException Any SAX exception, possibly 87 * wrapping another exception. 88 */ 89 public abstract void startDocument () 90 throws SAXException; 91 92 93 /** 94 * Receive notification of the end of a document. 95 * 96 * <p>The SAX parser will invoke this method only once, and it will 97 * be the last method invoked during the parse. The parser shall 98 * not invoke this method until it has either abandoned parsing 99 * (because of an unrecoverable error) or reached the end of 100 * input.</p> 101 * 102 * @exception org.xml.sax.SAXException Any SAX exception, possibly 103 * wrapping another exception. 104 */ 105 public abstract void endDocument () 106 throws SAXException; 107 108 109 /** 110 * Receive notification of the beginning of an element. 111 * 112 * <p>The Parser will invoke this method at the beginning of every 113 * element in the XML document; there will be a corresponding 114 * endElement() event for every startElement() event (even when the 115 * element is empty). All of the element's content will be 116 * reported, in order, before the corresponding endElement() 117 * event.</p> 118 * 119 * <p>If the element name has a namespace prefix, the prefix will 120 * still be attached. Note that the attribute list provided will 121 * contain only attributes with explicit values (specified or 122 * defaulted): #IMPLIED attributes will be omitted.</p> 123 * 124 * @param name The element type name. 125 * @param atts The attributes attached to the element, if any. 126 * @exception org.xml.sax.SAXException Any SAX exception, possibly 127 * wrapping another exception. 128 * @see #endElement 129 * @see org.xml.sax.AttributeList 130 */ 131 public abstract void startElement (String name, AttributeList atts) 132 throws SAXException; 133 134 135 /** 136 * Receive notification of the end of an element. 137 * 138 * <p>The SAX parser will invoke this method at the end of every 139 * element in the XML document; there will be a corresponding 140 * startElement() event for every endElement() event (even when the 141 * element is empty).</p> 142 * 143 * <p>If the element name has a namespace prefix, the prefix will 144 * still be attached to the name.</p> 145 * 146 * @param name The element type name 147 * @exception org.xml.sax.SAXException Any SAX exception, possibly 148 * wrapping another exception. 149 */ 150 public abstract void endElement (String name) 151 throws SAXException; 152 153 154 /** 155 * Receive notification of character data. 156 * 157 * <p>The Parser will call this method to report each chunk of 158 * character data. SAX parsers may return all contiguous character 159 * data in a single chunk, or they may split it into several 160 * chunks; however, all of the characters in any single event 161 * must come from the same external entity, so that the Locator 162 * provides useful information.</p> 163 * 164 * <p>The application must not attempt to read from the array 165 * outside of the specified range.</p> 166 * 167 * <p>Note that some parsers will report whitespace using the 168 * ignorableWhitespace() method rather than this one (validating 169 * parsers must do so).</p> 170 * 171 * @param ch The characters from the XML document. 172 * @param start The start position in the array. 173 * @param length The number of characters to read from the array. 174 * @exception org.xml.sax.SAXException Any SAX exception, possibly 175 * wrapping another exception. 176 * @see #ignorableWhitespace 177 * @see org.xml.sax.Locator 178 */ 179 public abstract void characters (char ch[], int start, int length) 180 throws SAXException; 181 182 183 /** 184 * Receive notification of ignorable whitespace in element content. 185 * 186 * <p>Validating Parsers must use this method to report each chunk 187 * of ignorable whitespace (see the W3C XML 1.0 recommendation, 188 * section 2.10): non-validating parsers may also use this method 189 * if they are capable of parsing and using content models.</p> 190 * 191 * <p>SAX parsers may return all contiguous whitespace in a single 192 * chunk, or they may split it into several chunks; however, all of 193 * the characters in any single event must come from the same 194 * external entity, so that the Locator provides useful 195 * information.</p> 196 * 197 * <p>The application must not attempt to read from the array 198 * outside of the specified range.</p> 199 * 200 * @param ch The characters from the XML document. 201 * @param start The start position in the array. 202 * @param length The number of characters to read from the array. 203 * @exception org.xml.sax.SAXException Any SAX exception, possibly 204 * wrapping another exception. 205 * @see #characters 206 */ 207 public abstract void ignorableWhitespace (char ch[], int start, int length) 208 throws SAXException; 209 210 211 /** 212 * Receive notification of a processing instruction. 213 * 214 * <p>The Parser will invoke this method once for each processing 215 * instruction found: note that processing instructions may occur 216 * before or after the main document element.</p> 217 * 218 * <p>A SAX parser should never report an XML declaration (XML 1.0, 219 * section 2.8) or a text declaration (XML 1.0, section 4.3.1) 220 * using this method.</p> 221 * 222 * @param target The processing instruction target. 223 * @param data The processing instruction data, or null if 224 * none was supplied. 225 * @exception org.xml.sax.SAXException Any SAX exception, possibly 226 * wrapping another exception. 227 */ 228 public abstract void processingInstruction (String target, String data) 229 throws SAXException; 230 231 } 232 233 // end of DocumentHandler.java 234
