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