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