1 /* 2 * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package org.xml.sax; 27 28 /** 29 * Receive notification of general document events. 30 * 31 * <p>This was the main event-handling interface for SAX1; in 32 * SAX2, it has been replaced by {@link org.xml.sax.ContentHandler 33 * ContentHandler}, which provides Namespace support and reporting 34 * of skipped entities. This interface is included in SAX2 only 35 * to support legacy SAX1 applications.</p> 36 * 37 * <p>The order of events in this interface is very important, and 38 * mirrors the order of information in the document itself. For 39 * example, all of an element's content (character data, processing 40 * instructions, and/or subelements) will appear, in order, between 41 * the startElement event and the corresponding endElement event.</p> 42 * 43 * <p>Application writers who do not want to implement the entire 44 * interface can derive a class from HandlerBase, which implements 45 * the default functionality; parser writers can instantiate 46 * HandlerBase to obtain a default handler. The application can find 47 * the location of any document event using the Locator interface 48 * supplied by the Parser through the setDocumentLocator method.</p> 49 * 50 * @deprecated This interface has been replaced by the SAX2 51 * {@link org.xml.sax.ContentHandler ContentHandler} 52 * interface, which includes Namespace support. 53 * @since 1.4, SAX 1.0 54 * @author David Megginson 55 * @see org.xml.sax.Parser#setDocumentHandler 56 * @see org.xml.sax.Locator 57 * @see org.xml.sax.HandlerBase 58 */ 59 @Deprecated(since="1.5") 60 public interface DocumentHandler { 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 DocumentHandler 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 abstract 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 methods in this interface or in DTDHandler (except for 96 * setDocumentLocator).</p> 97 * 98 * @throws org.xml.sax.SAXException Any SAX exception, possibly 99 * wrapping another exception. 100 */ 101 public abstract void startDocument () 102 throws SAXException; 103 104 105 /** 106 * Receive notification of the end of a document. 107 * 108 * <p>The SAX parser will invoke this method only once, and it will 109 * be the last method invoked during the parse. The parser shall 110 * not invoke this method until it has either abandoned parsing 111 * (because of an unrecoverable error) or reached the end of 112 * input.</p> 113 * 114 * @throws org.xml.sax.SAXException Any SAX exception, possibly 115 * wrapping another exception. 116 */ 117 public abstract void endDocument () 118 throws SAXException; 119 120 121 /** 122 * Receive notification of the beginning of an element. 123 * 124 * <p>The Parser will invoke this method at the beginning of every 125 * element in the XML document; there will be a corresponding 126 * endElement() event for every startElement() event (even when the 127 * element is empty). All of the element's content will be 128 * reported, in order, before the corresponding endElement() 129 * event.</p> 130 * 131 * <p>If the element name has a namespace prefix, the prefix will 132 * still be attached. Note that the attribute list provided will 133 * contain only attributes with explicit values (specified or 134 * defaulted): #IMPLIED attributes will be omitted.</p> 135 * 136 * @param name The element type name. 137 * @param atts The attributes attached to the element, if any. 138 * @throws org.xml.sax.SAXException Any SAX exception, possibly 139 * wrapping another exception. 140 * @see #endElement 141 * @see org.xml.sax.AttributeList 142 */ 143 public abstract void startElement (String name, AttributeList atts) 144 throws SAXException; 145 146 147 /** 148 * Receive notification of the end of an element. 149 * 150 * <p>The SAX parser will invoke this method at the end of every 151 * element in the XML document; there will be a corresponding 152 * startElement() event for every endElement() event (even when the 153 * element is empty).</p> 154 * 155 * <p>If the element name has a namespace prefix, the prefix will 156 * still be attached to the name.</p> 157 * 158 * @param name The element type name 159 * @throws org.xml.sax.SAXException Any SAX exception, possibly 160 * wrapping another exception. 161 */ 162 public abstract void endElement (String name) 163 throws SAXException; 164 165 166 /** 167 * Receive notification of character data. 168 * 169 * <p>The Parser will call this method to report each chunk of 170 * character data. SAX parsers may return all contiguous character 171 * data in a single chunk, or they may split it into several 172 * chunks; however, all of the characters in any single event 173 * must come from the same external entity, so that the Locator 174 * provides useful information.</p> 175 * 176 * <p>The application must not attempt to read from the array 177 * outside of the specified range.</p> 178 * 179 * <p>Note that some parsers will report whitespace using the 180 * ignorableWhitespace() method rather than this one (validating 181 * parsers must do so).</p> 182 * 183 * @param ch The characters from the XML document. 184 * @param start The start position in the array. 185 * @param length The number of characters to read from the array. 186 * @throws org.xml.sax.SAXException Any SAX exception, possibly 187 * wrapping another exception. 188 * @see #ignorableWhitespace 189 * @see org.xml.sax.Locator 190 */ 191 public abstract void characters (char ch[], int start, int length) 192 throws SAXException; 193 194 195 /** 196 * Receive notification of ignorable whitespace in element content. 197 * 198 * <p>Validating Parsers must use this method to report each chunk 199 * of ignorable whitespace (see the W3C XML 1.0 recommendation, 200 * section 2.10): non-validating parsers may also use this method 201 * if they are capable of parsing and using content models.</p> 202 * 203 * <p>SAX parsers may return all contiguous whitespace in a single 204 * chunk, or they may split it into several chunks; however, all of 205 * the characters in any single event must come from the same 206 * external entity, so that the Locator provides useful 207 * information.</p> 208 * 209 * <p>The application must not attempt to read from the array 210 * outside of the specified range.</p> 211 * 212 * @param ch The characters from the XML document. 213 * @param start The start position in the array. 214 * @param length The number of characters to read from the array. 215 * @throws org.xml.sax.SAXException Any SAX exception, possibly 216 * wrapping another exception. 217 * @see #characters 218 */ 219 public abstract void ignorableWhitespace (char ch[], int start, int length) 220 throws SAXException; 221 222 223 /** 224 * Receive notification of a processing instruction. 225 * 226 * <p>The Parser will invoke this method once for each processing 227 * instruction found: note that processing instructions may occur 228 * before or after the main document element.</p> 229 * 230 * <p>A SAX parser should never report an XML declaration (XML 1.0, 231 * section 2.8) or a text declaration (XML 1.0, section 4.3.1) 232 * using this method.</p> 233 * 234 * @param target The processing instruction target. 235 * @param data The processing instruction data, or null if 236 * none was supplied. 237 * @throws org.xml.sax.SAXException Any SAX exception, possibly 238 * wrapping another exception. 239 */ 240 public abstract void processingInstruction (String target, String data) 241 throws SAXException; 242 243 } 244 245 // end of DocumentHandler.java