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 // 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 jdk.internal.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 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 /** 131 * Receive notification of the end of a document. 132 * 133 * <p><strong>There is an apparent contradiction between the 134 * documentation for this method and the documentation for {@link 135 * org.xml.sax.ErrorHandler#fatalError}. Until this ambiguity is 136 * resolved in a future major release, clients should make no 137 * assumptions about whether endDocument() will or will not be 138 * invoked when the parser has reported a fatalError() or thrown 139 * an exception.</strong></p> 140 * 141 * <p>The SAX parser will invoke this method only once, and it will 142 * be the last method invoked during the parse. The parser shall 143 * not invoke this method until it has either abandoned parsing 144 * (because of an unrecoverable error) or reached the end of 145 * input.</p> 146 * 147 * @throws org.xml.sax.SAXException any SAX exception, possibly 148 * wrapping another exception 149 * @see #startDocument 150 */ 151 public void endDocument() 152 throws SAXException; 153 154 155 /** 156 * Begin the scope of a prefix-URI Namespace mapping. 157 * 158 * <p>The information from this event is not necessary for 159 * normal Namespace processing: the SAX XML reader will 160 * automatically replace prefixes for element and attribute 161 * names when the <code>http://xml.org/sax/features/namespaces</code> 162 * feature is <var>true</var> (the default).</p> 163 * 164 * <p>There are cases, however, when applications need to 165 * use prefixes in character data or in attribute values, 166 * where they cannot safely be expanded automatically; the 167 * start/endPrefixMapping event supplies the information 168 * to the application to expand prefixes in those contexts 169 * itself, if necessary.</p> 170 * 171 * <p>Note that start/endPrefixMapping events are not 172 * guaranteed to be properly nested relative to each other: 173 * all startPrefixMapping events will occur immediately before the 174 * corresponding {@link #startElement startElement} event, 175 * and all {@link #endPrefixMapping endPrefixMapping} 176 * events will occur immediately after the corresponding 177 * {@link #endElement endElement} event, 178 * but their order is not otherwise 179 * guaranteed.</p> 180 * 181 * <p>There should never be start/endPrefixMapping events for the 182 * "xml" prefix, since it is predeclared and immutable.</p> 183 * 184 * @param prefix the Namespace prefix being declared. 185 * An empty string is used for the default element namespace, 186 * which has no prefix. 187 * @param uri the Namespace URI the prefix is mapped to 188 * @throws org.xml.sax.SAXException the client may throw 189 * an exception during processing 190 * @see #endPrefixMapping 191 * @see #startElement 192 */ 193 public void startPrefixMapping (String prefix, String uri) 194 throws SAXException; 195 196 197 /** 198 * End the scope of a prefix-URI mapping. 199 * 200 * <p>See {@link #startPrefixMapping startPrefixMapping} for 201 * details. These events will always occur immediately after the 202 * corresponding {@link #endElement endElement} event, but the order of 203 * {@link #endPrefixMapping endPrefixMapping} events is not otherwise 204 * guaranteed.</p> 205 * 206 * @param prefix the prefix that was being mapped. 207 * This is the empty string when a default mapping scope ends. 208 * @throws org.xml.sax.SAXException the client may throw 209 * an exception during processing 210 * @see #startPrefixMapping 211 * @see #endElement 212 */ 213 public void endPrefixMapping (String prefix) 214 throws SAXException; 215 216 217 /** 218 * Receive notification of the beginning of an element. 219 * 220 * <p>The Parser will invoke this method at the beginning of every 221 * element in the XML document; there will be a corresponding 222 * {@link #endElement endElement} event for every startElement event 223 * (even when the element is empty). All of the element's content will be 224 * reported, in order, before the corresponding endElement 225 * event.</p> 226 * 227 * <p>This event allows up to three name components for each 228 * element:</p> 229 * 230 * <ol> 231 * <li>the Namespace URI;</li> 232 * <li>the local name; and</li> 233 * <li>the qualified (prefixed) name.</li> 234 * </ol> 235 * 236 * <p>Any or all of these may be provided, depending on the 237 * values of the <var>http://xml.org/sax/features/namespaces</var> 238 * and the <var>http://xml.org/sax/features/namespace-prefixes</var> 239 * properties:</p> 240 * 241 * <ul> 242 * <li>the Namespace URI and local name are required when 243 * the namespaces property is <var>true</var> (the default), and are 244 * optional when the namespaces property is <var>false</var> (if one is 245 * specified, both must be);</li> 246 * <li>the qualified name is required when the namespace-prefixes property 247 * is <var>true</var>, and is optional when the namespace-prefixes property 248 * is <var>false</var> (the default).</li> 249 * </ul> 250 * 251 * <p>Note that the attribute list provided will contain only 252 * attributes with explicit values (specified or defaulted): 253 * #IMPLIED attributes will be omitted. The attribute list 254 * will contain attributes used for Namespace declarations 255 * (xmlns* attributes) only if the 256 * <code>http://xml.org/sax/features/namespace-prefixes</code> 257 * property is true (it is false by default, and support for a 258 * true value is optional).</p> 259 * 260 * <p>Like {@link #characters characters()}, attribute values may have 261 * characters that need more than one <code>char</code> value. </p> 262 * 263 * @param uri the Namespace URI, or the empty string if the 264 * element has no Namespace URI or if Namespace 265 * processing is not being performed 266 * @param localName the local name (without prefix), or the 267 * empty string if Namespace processing is not being 268 * performed 269 * @param qName the qualified name (with prefix), or the 270 * empty string if qualified names are not available 271 * @param atts the attributes attached to the element. If 272 * there are no attributes, it shall be an empty 273 * Attributes object. The value of this object after 274 * startElement returns is undefined 275 * @throws org.xml.sax.SAXException any SAX exception, possibly 276 * wrapping another exception 277 * @see #endElement 278 * @see org.xml.sax.Attributes 279 * @see org.xml.sax.helpers.AttributesImpl 280 */ 281 public void startElement (String uri, String localName, 282 String qName, Attributes atts) 283 throws SAXException; 284 285 286 /** 287 * Receive notification of the end of an element. 288 * 289 * <p>The SAX parser will invoke this method at the end of every 290 * element in the XML document; there will be a corresponding 291 * {@link #startElement startElement} event for every endElement 292 * event (even when the element is empty).</p> 293 * 294 * <p>For information on the names, see startElement.</p> 295 * 296 * @param uri the Namespace URI, or the empty string if the 297 * element has no Namespace URI or if Namespace 298 * processing is not being performed 299 * @param localName the local name (without prefix), or the 300 * empty string if Namespace processing is not being 301 * performed 302 * @param qName the qualified XML name (with prefix), or the 303 * empty string if qualified names are not available 304 * @throws org.xml.sax.SAXException any SAX exception, possibly 305 * wrapping another exception 306 */ 307 public void endElement (String uri, String localName, 308 String qName) 309 throws SAXException; 310 311 312 /** 313 * Receive notification of character data. 314 * 315 * <p>The Parser will call this method to report each chunk of 316 * character data. SAX parsers may return all contiguous character 317 * data in a single chunk, or they may split it into several 318 * chunks; however, all of the characters in any single event 319 * must come from the same external entity so that the Locator 320 * provides useful information.</p> 321 * 322 * <p>The application must not attempt to read from the array 323 * outside of the specified range.</p> 324 * 325 * <p>Individual characters may consist of more than one Java 326 * <code>char</code> value. There are two important cases where this 327 * happens, because characters can't be represented in just sixteen bits. 328 * In one case, characters are represented in a <em>Surrogate Pair</em>, 329 * using two special Unicode values. Such characters are in the so-called 330 * "Astral Planes", with a code point above U+FFFF. A second case involves 331 * composite characters, such as a base character combining with one or 332 * more accent characters. </p> 333 * 334 * <p> Your code should not assume that algorithms using 335 * <code>char</code>-at-a-time idioms will be working in character 336 * units; in some cases they will split characters. This is relevant 337 * wherever XML permits arbitrary characters, such as attribute values, 338 * processing instruction data, and comments as well as in data reported 339 * from this method. It's also generally relevant whenever Java code 340 * manipulates internationalized text; the issue isn't unique to XML.</p> 341 * 342 * <p>Note that some parsers will report whitespace in element 343 * content using the {@link #ignorableWhitespace ignorableWhitespace} 344 * method rather than this one (validating parsers <em>must</em> 345 * do so).</p> 346 * 347 * @param ch the characters from the XML document 348 * @param start the start position in the array 349 * @param length the number of characters to read from the array 350 * @throws org.xml.sax.SAXException any SAX exception, possibly 351 * wrapping another exception 352 * @see #ignorableWhitespace 353 * @see org.xml.sax.Locator 354 */ 355 public void characters (char ch[], int start, int length) 356 throws SAXException; 357 358 359 /** 360 * Receive notification of ignorable whitespace in element content. 361 * 362 * <p>Validating Parsers must use this method to report each chunk 363 * of whitespace in element content (see the W3C XML 1.0 364 * recommendation, section 2.10): non-validating parsers may also 365 * use this method if they are capable of parsing and using 366 * content models.</p> 367 * 368 * <p>SAX parsers may return all contiguous whitespace in a single 369 * chunk, or they may split it into several chunks; however, all of 370 * the characters in any single event must come from the same 371 * external entity, so that the Locator provides useful 372 * information.</p> 373 * 374 * <p>The application must not attempt to read from the array 375 * outside of the specified range.</p> 376 * 377 * @param ch the characters from the XML document 378 * @param start the start position in the array 379 * @param length the number of characters to read from the array 380 * @throws org.xml.sax.SAXException any SAX exception, possibly 381 * wrapping another exception 382 * @see #characters 383 */ 384 public void ignorableWhitespace (char ch[], int start, int length) 385 throws SAXException; 386 387 388 /** 389 * Receive notification of a processing instruction. 390 * 391 * <p>The Parser will invoke this method once for each processing 392 * instruction found: note that processing instructions may occur 393 * before or after the main document element.</p> 394 * 395 * <p>A SAX parser must never report an XML declaration (XML 1.0, 396 * section 2.8) or a text declaration (XML 1.0, section 4.3.1) 397 * using this method.</p> 398 * 399 * <p>Like {@link #characters characters()}, processing instruction 400 * data may have characters that need more than one <code>char</code> 401 * value. </p> 402 * 403 * @param target the processing instruction target 404 * @param data the processing instruction data, or null if 405 * none was supplied. The data does not include any 406 * whitespace separating it from the target 407 * @throws org.xml.sax.SAXException any SAX exception, possibly 408 * wrapping another exception 409 */ 410 public void processingInstruction (String target, String data) 411 throws SAXException; 412 413 414 /** 415 * Receive notification of a skipped entity. 416 * This is not called for entity references within markup constructs 417 * such as element start tags or markup declarations. (The XML 418 * recommendation requires reporting skipped external entities. 419 * SAX also reports internal entity expansion/non-expansion, except 420 * within markup constructs.) 421 * 422 * <p>The Parser will invoke this method each time the entity is 423 * skipped. Non-validating processors may skip entities if they 424 * have not seen the declarations (because, for example, the 425 * entity was declared in an external DTD subset). All processors 426 * may skip external entities, depending on the values of the 427 * <code>http://xml.org/sax/features/external-general-entities</code> 428 * and the 429 * <code>http://xml.org/sax/features/external-parameter-entities</code> 430 * properties.</p> 431 * 432 * @param name the name of the skipped entity. If it is a 433 * parameter entity, the name will begin with '%', and if 434 * it is the external DTD subset, it will be the string 435 * "[dtd]" 436 * @throws org.xml.sax.SAXException any SAX exception, possibly 437 * wrapping another exception 438 */ 439 public void skippedEntity (String name) 440 throws SAXException; 441 } 442 443 // end of ContentHandler.java