286N/A * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved. 286N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 286N/A * This code is free software; you can redistribute it and/or modify it 286N/A * under the terms of the GNU General Public License version 2 only, as 286N/A * published by the Free Software Foundation. Oracle designates this 286N/A * particular file as subject to the "Classpath" exception as provided 286N/A * by Oracle in the LICENSE file that accompanied this code. 286N/A * This code is distributed in the hope that it will be useful, but WITHOUT 286N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 286N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 286N/A * version 2 for more details (a copy is included in the LICENSE file that 286N/A * accompanied this code). 286N/A * You should have received a copy of the GNU General Public License version 286N/A * 2 along with this work; if not, write to the Free Software Foundation, 286N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 286N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 286N/A * or visit www.oracle.com if you need additional information or have any 286N/A// Written by David Megginson 286N/A// NO WARRANTY! This class is in the public domain. 286N/A * Receive notification of the logical content of a document. 286N/A * <em>This module, both source code and documentation, is in the 286N/A * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 286N/A * for further information. 286N/A * <p>This is the main interface that most SAX applications 286N/A * implement: if the application needs to be informed of basic parsing 286N/A * events, it implements this interface and registers an instance with 286N/A * setContentHandler} method. The parser uses the instance to report 286N/A * basic document-related events like the start and end of elements 286N/A * and character data.</p> 286N/A * <p>The order of events in this interface is very important, and 286N/A * mirrors the order of information in the document itself. For 286N/A * example, all of an element's content (character data, processing 286N/A * instructions, and/or subelements) will appear, in order, between 286N/A * the startElement event and the corresponding endElement event.</p> 286N/A * <p>This interface is similar to the now-deprecated SAX 1.0 286N/A * DocumentHandler interface, but it adds support for Namespaces 286N/A * and for reporting skipped entities (in non-validating XML 286N/A * <p>Implementors should note that there is also a 286N/A * <code>ContentHandler</code> class in the <code>java.net</code> 286N/A * package; that means that it's probably a bad idea to do</p> 286N/A * <pre>import java.net.*; 286N/A * <p>In fact, "import ...*" is usually a sign of sloppy programming 286N/A * anyway, so the user should consider this a feature rather than a 286N/A * @author David Megginson 286N/A * Receive an object for locating the origin of SAX document events. 286N/A * <p>SAX parsers are strongly encouraged (though not absolutely 286N/A * required) to supply a locator: if it does so, it must supply 286N/A * the locator to the application by invoking this method before 286N/A * invoking any of the other methods in the ContentHandler 286N/A * <p>The locator allows the application to determine the end 286N/A * position of any document-related event, even if the parser is 286N/A * not reporting an error. Typically, the application will 286N/A * use this information for reporting its own errors (such as 286N/A * character content that does not match an application's 286N/A * business rules). The information returned by the locator 286N/A * is probably not sufficient for use with a search engine.</p> 286N/A * <p>Note that the locator will return correct information only 286N/A * during the invocation SAX event callbacks after 286N/A * {@link #startDocument startDocument} returns and before 286N/A * {@link #endDocument endDocument} is called. The 286N/A * application should not attempt to use it at any other time.</p> 286N/A * @param locator an object that can return the location of 286N/A * any SAX document event 286N/A * Receive notification of the beginning of a document. 286N/A * <p>The SAX parser will invoke this method only once, before any 286N/A * other event callbacks (except for {@link #setDocumentLocator 286N/A * setDocumentLocator}).</p> 286N/A * @throws org.xml.sax.SAXException any SAX exception, possibly 286N/A * wrapping another exception 286N/A * Receive notification of the end of a document. 286N/A * <p><strong>There is an apparent contradiction between the 286N/A * documentation for this method and the documentation for {@link 286N/A * org.xml.sax.ErrorHandler#fatalError}. Until this ambiguity is 286N/A * resolved in a future major release, clients should make no 286N/A * assumptions about whether endDocument() will or will not be 286N/A * invoked when the parser has reported a fatalError() or thrown 286N/A * an exception.</strong></p> 286N/A * <p>The SAX parser will invoke this method only once, and it will 286N/A * be the last method invoked during the parse. The parser shall 286N/A * not invoke this method until it has either abandoned parsing 286N/A * (because of an unrecoverable error) or reached the end of 286N/A * @throws org.xml.sax.SAXException any SAX exception, possibly 286N/A * wrapping another exception 286N/A * Begin the scope of a prefix-URI Namespace mapping. 286N/A * <p>The information from this event is not necessary for 286N/A * normal Namespace processing: the SAX XML reader will 286N/A * automatically replace prefixes for element and attribute 286N/A * feature is <var>true</var> (the default).</p> 286N/A * <p>There are cases, however, when applications need to 286N/A * use prefixes in character data or in attribute values, 286N/A * where they cannot safely be expanded automatically; the 286N/A * to the application to expand prefixes in those contexts 286N/A * itself, if necessary.</p> 286N/A * guaranteed to be properly nested relative to each other: 286N/A * all startPrefixMapping events will occur immediately before the 286N/A * corresponding {@link #startElement startElement} event, 286N/A * and all {@link #endPrefixMapping endPrefixMapping} 286N/A * events will occur immediately after the corresponding 286N/A * {@link #endElement endElement} event, 286N/A * but their order is not otherwise 286N/A * "xml" prefix, since it is predeclared and immutable.</p> 286N/A * @param prefix the Namespace prefix being declared. 286N/A * An empty string is used for the default element namespace, 286N/A * @param uri the Namespace URI the prefix is mapped to 286N/A * @throws org.xml.sax.SAXException the client may throw 286N/A * an exception during processing 286N/A * @see #endPrefixMapping 286N/A * End the scope of a prefix-URI mapping. 286N/A * <p>See {@link #startPrefixMapping startPrefixMapping} for 286N/A * details. These events will always occur immediately after the 286N/A * corresponding {@link #endElement endElement} event, but the order of 286N/A * {@link #endPrefixMapping endPrefixMapping} events is not otherwise 286N/A * @param prefix the prefix that was being mapped. 286N/A * This is the empty string when a default mapping scope ends. 286N/A * @throws org.xml.sax.SAXException the client may throw 286N/A * an exception during processing 286N/A * @see #startPrefixMapping 286N/A * Receive notification of the beginning of an element. 286N/A * <p>The Parser will invoke this method at the beginning of every 286N/A * element in the XML document; there will be a corresponding 286N/A * {@link #endElement endElement} event for every startElement event 286N/A * (even when the element is empty). All of the element's content will be 286N/A * reported, in order, before the corresponding endElement 286N/A * <p>This event allows up to three name components for each 286N/A * <li>the Namespace URI;</li> 286N/A * <li>the local name; and</li> 286N/A * <li>the qualified (prefixed) name.</li> 286N/A * <p>Any or all of these may be provided, depending on the 286N/A * <li>the Namespace URI and local name are required when 286N/A * the namespaces property is <var>true</var> (the default), and are 286N/A * optional when the namespaces property is <var>false</var> (if one is 286N/A * specified, both must be);</li> 286N/A * <li>the qualified name is required when the namespace-prefixes property 286N/A * is <var>true</var>, and is optional when the namespace-prefixes property 286N/A * is <var>false</var> (the default).</li> 286N/A * <p>Note that the attribute list provided will contain only 286N/A * attributes with explicit values (specified or defaulted): 286N/A * #IMPLIED attributes will be omitted. The attribute list 286N/A * will contain attributes used for Namespace declarations 286N/A * (xmlns* attributes) only if the 286N/A * property is true (it is false by default, and support for a 286N/A * true value is optional).</p> 286N/A * <p>Like {@link #characters characters()}, attribute values may have 286N/A * characters that need more than one <code>char</code> value. </p> 286N/A * @param uri the Namespace URI, or the empty string if the 286N/A * element has no Namespace URI or if Namespace 286N/A * processing is not being performed 286N/A * @param localName the local name (without prefix), or the 286N/A * empty string if Namespace processing is not being 286N/A * @param qName the qualified name (with prefix), or the 286N/A * empty string if qualified names are not available 286N/A * @param atts the attributes attached to the element. If 286N/A * there are no attributes, it shall be an empty 286N/A * Attributes object. The value of this object after 286N/A * startElement returns is undefined 286N/A * @throws org.xml.sax.SAXException any SAX exception, possibly 286N/A * wrapping another exception 286N/A * Receive notification of the end of an element. 286N/A * <p>The SAX parser will invoke this method at the end of every 286N/A * element in the XML document; there will be a corresponding 286N/A * {@link #startElement startElement} event for every endElement 286N/A * event (even when the element is empty).</p> 286N/A * <p>For information on the names, see startElement.</p> 286N/A * @param uri the Namespace URI, or the empty string if the 286N/A * element has no Namespace URI or if Namespace 286N/A * processing is not being performed 286N/A * @param localName the local name (without prefix), or the 286N/A * empty string if Namespace processing is not being 286N/A * @param qName the qualified XML name (with prefix), or the 286N/A * empty string if qualified names are not available 286N/A * @throws org.xml.sax.SAXException any SAX exception, possibly 286N/A * wrapping another exception 286N/A * Receive notification of character data. 286N/A * <p>The Parser will call this method to report each chunk of 286N/A * character data. SAX parsers may return all contiguous character 286N/A * data in a single chunk, or they may split it into several 286N/A * chunks; however, all of the characters in any single event 286N/A * must come from the same external entity so that the Locator 286N/A * provides useful information.</p> 286N/A * <p>The application must not attempt to read from the array 286N/A * outside of the specified range.</p> 286N/A * <p>Individual characters may consist of more than one Java 286N/A * <code>char</code> value. There are two important cases where this 286N/A * happens, because characters can't be represented in just sixteen bits. 286N/A * In one case, characters are represented in a <em>Surrogate Pair</em>, 286N/A * using two special Unicode values. Such characters are in the so-called 286N/A * "Astral Planes", with a code point above U+FFFF. A second case involves 286N/A * composite characters, such as a base character combining with one or 286N/A * more accent characters. </p> 286N/A * <p> Your code should not assume that algorithms using 286N/A * <code>char</code>-at-a-time idioms will be working in character 286N/A * units; in some cases they will split characters. This is relevant 286N/A * wherever XML permits arbitrary characters, such as attribute values, 286N/A * processing instruction data, and comments as well as in data reported 286N/A * from this method. It's also generally relevant whenever Java code 286N/A * manipulates internationalized text; the issue isn't unique to XML.</p> 286N/A * <p>Note that some parsers will report whitespace in element 286N/A * content using the {@link #ignorableWhitespace ignorableWhitespace} 286N/A * method rather than this one (validating parsers <em>must</em> 286N/A * @param ch the characters from the XML document 286N/A * @param start the start position in the array 286N/A * @param length the number of characters to read from the array 286N/A * @throws org.xml.sax.SAXException any SAX exception, possibly 286N/A * wrapping another exception 286N/A * @see #ignorableWhitespace 286N/A * Receive notification of ignorable whitespace in element content. 286N/A * <p>Validating Parsers must use this method to report each chunk 286N/A * of whitespace in element content (see the W3C XML 1.0 286N/A * recommendation, section 2.10): non-validating parsers may also 286N/A * use this method if they are capable of parsing and using 286N/A * <p>SAX parsers may return all contiguous whitespace in a single 286N/A * chunk, or they may split it into several chunks; however, all of 286N/A * the characters in any single event must come from the same 286N/A * external entity, so that the Locator provides useful 286N/A * <p>The application must not attempt to read from the array 286N/A * outside of the specified range.</p> 286N/A * @param ch the characters from the XML document 286N/A * @param start the start position in the array 286N/A * @param length the number of characters to read from the array 286N/A * @throws org.xml.sax.SAXException any SAX exception, possibly 286N/A * wrapping another exception 286N/A * Receive notification of a processing instruction. 286N/A * <p>The Parser will invoke this method once for each processing 286N/A * instruction found: note that processing instructions may occur 286N/A * before or after the main document element.</p> 286N/A * <p>A SAX parser must never report an XML declaration (XML 1.0, 286N/A * section 2.8) or a text declaration (XML 1.0, section 4.3.1) 286N/A * using this method.</p> 286N/A * <p>Like {@link #characters characters()}, processing instruction 286N/A * data may have characters that need more than one <code>char</code> 286N/A * @param target the processing instruction target 286N/A * @param data the processing instruction data, or null if 286N/A * none was supplied. The data does not include any 286N/A * whitespace separating it from the target 286N/A * @throws org.xml.sax.SAXException any SAX exception, possibly 286N/A * wrapping another exception 286N/A * Receive notification of a skipped entity. 286N/A * This is not called for entity references within markup constructs 286N/A * such as element start tags or markup declarations. (The XML 286N/A * recommendation requires reporting skipped external entities. 286N/A * within markup constructs.) 286N/A * <p>The Parser will invoke this method each time the entity is 286N/A * skipped. Non-validating processors may skip entities if they 286N/A * have not seen the declarations (because, for example, the 286N/A * entity was declared in an external DTD subset). All processors 286N/A * may skip external entities, depending on the values of the 286N/A * @param name the name of the skipped entity. If it is a 286N/A * parameter entity, the name will begin with '%', and if 286N/A * it is the external DTD subset, it will be the string 286N/A * @throws org.xml.sax.SAXException any SAX exception, possibly 286N/A * wrapping another exception