1 /* 2 * Copyright (c) 2000, 2019, 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 /** 30 * Receive notification of the logical content of a document. 31 * 32 * <p>This is the main interface that most SAX applications 33 * implement: if the application needs to be informed of basic parsing 34 * events, it implements this interface and registers an instance with 35 * the SAX parser using the {@link org.xml.sax.XMLReader#setContentHandler 36 * setContentHandler} method. The parser uses the instance to report 37 * basic document-related events like the start and end of elements 38 * and character data.</p> 39 * 40 * <p>The order of events in this interface is very important, and 41 * mirrors the order of information in the document itself. For 42 * example, all of an element's content (character data, processing 43 * instructions, and/or subelements) will appear, in order, between 44 * the startElement event and the corresponding endElement event.</p> 45 * 46 * <p>This interface is similar to the now-deprecated SAX 1.0 47 * DocumentHandler interface, but it adds support for Namespaces 48 * and for reporting skipped entities (in non-validating XML 49 * processors).</p> 50 * 51 * <p>Implementors should note that there is also a 52 * <code>ContentHandler</code> class in the <code>java.net</code> 53 * package; that means that it's probably a bad idea to do</p> 54 * 55 * <pre>import java.net.*; 56 * import org.xml.sax.*; 57 * </pre> 58 * 59 * <p>In fact, "import ...*" is usually a sign of sloppy programming 60 * anyway, so the user should consider this a feature rather than a 61 * bug.</p> 62 * 63 * @since 1.4, SAX 2.0 64 * @author David Megginson 65 * @see org.xml.sax.XMLReader 66 * @see org.xml.sax.DTDHandler 67 * @see org.xml.sax.ErrorHandler 68 */ 69 public interface ContentHandler 70 { 71 72 /** 73 * Receive an object for locating the origin of SAX document events. 74 * 75 * <p>SAX parsers are strongly encouraged (though not absolutely 76 * required) to supply a locator: if it does so, it must supply 77 * the locator to the application by invoking this method before 78 * invoking any of the other methods in the ContentHandler 79 * interface.</p> 80 * 81 * <p>The locator allows the application to determine the end 82 * position of any document-related event, even if the parser is 83 * not reporting an error. Typically, the application will 84 * use this information for reporting its own errors (such as 85 * character content that does not match an application's 86 * business rules). The information returned by the locator 87 * is probably not sufficient for use with a search engine.</p> 88 * 89 * <p>Note that the locator will return correct information only 90 * during the invocation SAX event callbacks after 91 * {@link #startDocument startDocument} returns and before 92 * {@link #endDocument endDocument} is called. The 93 * application should not attempt to use it at any other time.</p> 94 * 95 * @param locator an object that can return the location of 96 * any SAX document event 97 * @see org.xml.sax.Locator 98 */ 99 public void setDocumentLocator (Locator locator); 100 101 102 /** 103 * Receive notification of the beginning of a document. 104 * 105 * <p>The SAX parser will invoke this method only once, before any 106 * other event callbacks (except for {@link #setDocumentLocator 107 * setDocumentLocator}).</p> 108 * 109 * @throws org.xml.sax.SAXException any SAX exception, possibly 110 * wrapping another exception 111 * @see #endDocument 112 */ 113 public void startDocument () 114 throws SAXException; 115 116 /** 117 * Receives notification of the XML declaration. 118 * 119 * @implSpec 120 * The default implementation in the SAX API is to do nothing. 121 * 122 * @param version the version string as in the input document, null if not 123 * specified 124 * @param encoding the encoding string as in the input document, null if not 125 * specified 126 * @param standalone the standalone string as in the input document, null if 127 * not specified 128 * 129 * @throws SAXException if the application wants to report an error or 130 * interrupt the parsing process 131 * 132 * @since 14 133 */ 134 default void declaration(String version, String encoding, String standalone) 135 throws SAXException 136 { 137 //no op 138 } 139 140 /** 141 * Receive notification of the end of a document. 142 * 143 * <p> 144 * This method is invoked by the parser to signal it has reached the end of 145 * the document after successfully completing the parsing process. 146 * After the event, the parser will return the control to the application. 147 * 148 * @apiNote In case of a fatal error, the parser may choose to stop the 149 * parsing process with a {@link SAXException}, in which case, this method 150 * will never be called. Refer to 151 * {@link ErrorHandler#fatalError(org.xml.sax.SAXParseException)}. 152 * 153 * @throws org.xml.sax.SAXException any SAX exception, possibly 154 * wrapping another exception 155 * @see #startDocument 156 */ 157 public void endDocument() 158 throws SAXException; 159 160 161 /** 162 * Begin the scope of a prefix-URI Namespace mapping. 163 * 164 * <p>The information from this event is not necessary for 165 * normal Namespace processing: the SAX XML reader will 166 * automatically replace prefixes for element and attribute 167 * names when the <code>http://xml.org/sax/features/namespaces</code> 168 * feature is <var>true</var> (the default).</p> 169 * 170 * <p>There are cases, however, when applications need to 171 * use prefixes in character data or in attribute values, 172 * where they cannot safely be expanded automatically; the 173 * start/endPrefixMapping event supplies the information 174 * to the application to expand prefixes in those contexts 175 * itself, if necessary.</p> 176 * 177 * <p>Note that start/endPrefixMapping events are not 178 * guaranteed to be properly nested relative to each other: 179 * all startPrefixMapping events will occur immediately before the 180 * corresponding {@link #startElement startElement} event, 181 * and all {@link #endPrefixMapping endPrefixMapping} 182 * events will occur immediately after the corresponding 183 * {@link #endElement endElement} event, 184 * but their order is not otherwise 185 * guaranteed.</p> 186 * 187 * <p>There should never be start/endPrefixMapping events for the 188 * "xml" prefix, since it is predeclared and immutable.</p> 189 * 190 * @param prefix the Namespace prefix being declared. 191 * An empty string is used for the default element namespace, 192 * which has no prefix. 193 * @param uri the Namespace URI the prefix is mapped to 194 * @throws org.xml.sax.SAXException the client may throw 195 * an exception during processing 196 * @see #endPrefixMapping 197 * @see #startElement 198 */ 199 public void startPrefixMapping (String prefix, String uri) 200 throws SAXException; 201 202 203 /** 204 * End the scope of a prefix-URI mapping. 205 * 206 * <p>See {@link #startPrefixMapping startPrefixMapping} for 207 * details. These events will always occur immediately after the 208 * corresponding {@link #endElement endElement} event, but the order of 209 * {@link #endPrefixMapping endPrefixMapping} events is not otherwise 210 * guaranteed.</p> 211 * 212 * @param prefix the prefix that was being mapped. 213 * This is the empty string when a default mapping scope ends. 214 * @throws org.xml.sax.SAXException the client may throw 215 * an exception during processing 216 * @see #startPrefixMapping 217 * @see #endElement 218 */ 219 public void endPrefixMapping (String prefix) 220 throws SAXException; 221 222 223 /** 224 * Receive notification of the beginning of an element. 225 * 226 * <p>The Parser will invoke this method at the beginning of every 227 * element in the XML document; there will be a corresponding 228 * {@link #endElement endElement} event for every startElement event 229 * (even when the element is empty). All of the element's content will be 230 * reported, in order, before the corresponding endElement 231 * event.</p> 232 * 233 * <p>This event allows up to three name components for each 234 * element:</p> 235 * 236 * <ol> 237 * <li>the Namespace URI;</li> 238 * <li>the local name; and</li> 239 * <li>the qualified (prefixed) name.</li> 240 * </ol> 241 * 242 * <p>Any or all of these may be provided, depending on the 243 * values of the <var>http://xml.org/sax/features/namespaces</var> 244 * and the <var>http://xml.org/sax/features/namespace-prefixes</var> 245 * properties:</p> 246 * 247 * <ul> 248 * <li>the Namespace URI and local name are required when 249 * the namespaces property is <var>true</var> (the default), and are 250 * optional when the namespaces property is <var>false</var> (if one is 251 * specified, both must be);</li> 252 * <li>the qualified name is required when the namespace-prefixes property 253 * is <var>true</var>, and is optional when the namespace-prefixes property 254 * is <var>false</var> (the default).</li> 255 * </ul> 256 * 257 * <p>Note that the attribute list provided will contain only 258 * attributes with explicit values (specified or defaulted): 259 * #IMPLIED attributes will be omitted. The attribute list 260 * will contain attributes used for Namespace declarations 261 * (xmlns* attributes) only if the 262 * <code>http://xml.org/sax/features/namespace-prefixes</code> 263 * property is true (it is false by default, and support for a 264 * true value is optional).</p> 265 * 266 * <p>Like {@link #characters characters()}, attribute values may have 267 * characters that need more than one <code>char</code> value. </p> 268 * 269 * @param uri the Namespace URI, or the empty string if the 270 * element has no Namespace URI or if Namespace 271 * processing is not being performed 272 * @param localName the local name (without prefix), or the 273 * empty string if Namespace processing is not being 274 * performed 275 * @param qName the qualified name (with prefix), or the 276 * empty string if qualified names are not available 277 * @param atts the attributes attached to the element. If 278 * there are no attributes, it shall be an empty 279 * Attributes object. The value of this object after 280 * startElement returns is undefined 281 * @throws org.xml.sax.SAXException any SAX exception, possibly 282 * wrapping another exception 283 * @see #endElement 284 * @see org.xml.sax.Attributes 285 * @see org.xml.sax.helpers.AttributesImpl 286 */ 287 public void startElement (String uri, String localName, 288 String qName, Attributes atts) 289 throws SAXException; 290 291 292 /** 293 * Receive notification of the end of an element. 294 * 295 * <p>The SAX parser will invoke this method at the end of every 296 * element in the XML document; there will be a corresponding 297 * {@link #startElement startElement} event for every endElement 298 * event (even when the element is empty).</p> 299 * 300 * <p>For information on the names, see startElement.</p> 301 * 302 * @param uri the Namespace URI, or the empty string if the 303 * element has no Namespace URI or if Namespace 304 * processing is not being performed 305 * @param localName the local name (without prefix), or the 306 * empty string if Namespace processing is not being 307 * performed 308 * @param qName the qualified XML name (with prefix), or the 309 * empty string if qualified names are not available 310 * @throws org.xml.sax.SAXException any SAX exception, possibly 311 * wrapping another exception 312 */ 313 public void endElement (String uri, String localName, 314 String qName) 315 throws SAXException; 316 317 318 /** 319 * Receive notification of character data. 320 * 321 * <p>The Parser will call this method to report each chunk of 322 * character data. SAX parsers may return all contiguous character 323 * data in a single chunk, or they may split it into several 324 * chunks; however, all of the characters in any single event 325 * must come from the same external entity so that the Locator 326 * provides useful information.</p> 327 * 328 * <p>The application must not attempt to read from the array 329 * outside of the specified range.</p> 330 * 331 * <p>Individual characters may consist of more than one Java 332 * <code>char</code> value. There are two important cases where this 333 * happens, because characters can't be represented in just sixteen bits. 334 * In one case, characters are represented in a <em>Surrogate Pair</em>, 335 * using two special Unicode values. Such characters are in the so-called 336 * "Astral Planes", with a code point above U+FFFF. A second case involves 337 * composite characters, such as a base character combining with one or 338 * more accent characters. </p> 339 * 340 * <p> Your code should not assume that algorithms using 341 * <code>char</code>-at-a-time idioms will be working in character 342 * units; in some cases they will split characters. This is relevant 343 * wherever XML permits arbitrary characters, such as attribute values, 344 * processing instruction data, and comments as well as in data reported 345 * from this method. It's also generally relevant whenever Java code 346 * manipulates internationalized text; the issue isn't unique to XML.</p> 347 * 348 * <p>Note that some parsers will report whitespace in element 349 * content using the {@link #ignorableWhitespace ignorableWhitespace} 350 * method rather than this one (validating parsers <em>must</em> 351 * do so).</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 #ignorableWhitespace 359 * @see org.xml.sax.Locator 360 */ 361 public void characters (char ch[], int start, int length) 362 throws SAXException; 363 364 365 /** 366 * Receive notification of ignorable whitespace in element content. 367 * 368 * <p>Validating Parsers must use this method to report each chunk 369 * of whitespace in element content (see the W3C XML 1.0 370 * recommendation, section 2.10): non-validating parsers may also 371 * use this method if they are capable of parsing and using 372 * content models.</p> 373 * 374 * <p>SAX parsers may return all contiguous whitespace in a single 375 * chunk, or they may split it into several chunks; however, all of 376 * the characters in any single event must come from the same 377 * external entity, so that the Locator provides useful 378 * information.</p> 379 * 380 * <p>The application must not attempt to read from the array 381 * outside of the specified range.</p> 382 * 383 * @param ch the characters from the XML document 384 * @param start the start position in the array 385 * @param length the number of characters to read from the array 386 * @throws org.xml.sax.SAXException any SAX exception, possibly 387 * wrapping another exception 388 * @see #characters 389 */ 390 public void ignorableWhitespace (char ch[], int start, int length) 391 throws SAXException; 392 393 394 /** 395 * Receive notification of a processing instruction. 396 * 397 * <p>The Parser will invoke this method once for each processing 398 * instruction found: note that processing instructions may occur 399 * before or after the main document element.</p> 400 * 401 * <p>A SAX parser must never report an XML declaration (XML 1.0, 402 * section 2.8) or a text declaration (XML 1.0, section 4.3.1) 403 * using this method.</p> 404 * 405 * <p>Like {@link #characters characters()}, processing instruction 406 * data may have characters that need more than one <code>char</code> 407 * value. </p> 408 * 409 * @param target the processing instruction target 410 * @param data the processing instruction data, or null if 411 * none was supplied. The data does not include any 412 * whitespace separating it from the target 413 * @throws org.xml.sax.SAXException any SAX exception, possibly 414 * wrapping another exception 415 */ 416 public void processingInstruction (String target, String data) 417 throws SAXException; 418 419 420 /** 421 * Receive notification of a skipped entity. 422 * This is not called for entity references within markup constructs 423 * such as element start tags or markup declarations. (The XML 424 * recommendation requires reporting skipped external entities. 425 * SAX also reports internal entity expansion/non-expansion, except 426 * within markup constructs.) 427 * 428 * <p>The Parser will invoke this method each time the entity is 429 * skipped. Non-validating processors may skip entities if they 430 * have not seen the declarations (because, for example, the 431 * entity was declared in an external DTD subset). All processors 432 * may skip external entities, depending on the values of the 433 * <code>http://xml.org/sax/features/external-general-entities</code> 434 * and the 435 * <code>http://xml.org/sax/features/external-parameter-entities</code> 436 * properties.</p> 437 * 438 * @param name the name of the skipped entity. If it is a 439 * parameter entity, the name will begin with '%', and if 440 * it is the external DTD subset, it will be the string 441 * "[dtd]" 442 * @throws org.xml.sax.SAXException any SAX exception, possibly 443 * wrapping another exception 444 */ 445 public void skippedEntity (String name) 446 throws SAXException; 447 } 448 449 // end of ContentHandler.java