/* |
|
* Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. |
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
* |
|
* This code is free software; you can redistribute it and/or modify it |
|
* under the terms of the GNU General Public License version 2 only, as |
|
* published by the Free Software Foundation. Oracle designates this |
|
* particular file as subject to the "Classpath" exception as provided |
|
* by Oracle in the LICENSE file that accompanied this code. |
|
* |
|
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
* version 2 for more details (a copy is included in the LICENSE file that |
|
* accompanied this code). |
|
* |
|
* You should have received a copy of the GNU General Public License version |
|
* 2 along with this work; if not, write to the Free Software Foundation, |
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
* |
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
* or visit www.oracle.com if you need additional information or have any |
|
* questions. |
|
*/ |
|
package org.xml.sax; |
|
/** |
|
* Receive notification of general document events. |
|
* |
|
* <p>This was the main event-handling interface for SAX1; in |
|
* SAX2, it has been replaced by {@link org.xml.sax.ContentHandler |
|
* ContentHandler}, which provides Namespace support and reporting |
|
* of skipped entities. This interface is included in SAX2 only |
|
* to support legacy SAX1 applications.</p> |
|
* |
|
* <p>The order of events in this interface is very important, and |
|
* mirrors the order of information in the document itself. For |
|
* example, all of an element's content (character data, processing |
|
* instructions, and/or subelements) will appear, in order, between |
|
* the startElement event and the corresponding endElement event.</p> |
|
* |
|
* <p>Application writers who do not want to implement the entire |
|
* interface can derive a class from HandlerBase, which implements |
|
* the default functionality; parser writers can instantiate |
|
* HandlerBase to obtain a default handler. The application can find |
|
* the location of any document event using the Locator interface |
|
* supplied by the Parser through the setDocumentLocator method.</p> |
|
* |
|
* @deprecated This interface has been replaced by the SAX2 |
|
* {@link org.xml.sax.ContentHandler ContentHandler} |
|
* interface, which includes Namespace support. |
|
* @since 1.4, SAX 1.0 |
|
* @author David Megginson |
|
* @see org.xml.sax.Parser#setDocumentHandler |
|
* @see org.xml.sax.Locator |
|
* @see org.xml.sax.HandlerBase |
|
*/ |
|
@Deprecated(since="1.5") |
|
public interface DocumentHandler { |
|
/** |
|
* Receive an object for locating the origin of SAX document events. |
|
* |
|
* <p>SAX parsers are strongly encouraged (though not absolutely |
|
* required) to supply a locator: if it does so, it must supply |
|
* the locator to the application by invoking this method before |
|
* invoking any of the other methods in the DocumentHandler |
|
* interface.</p> |
|
* |
|
* <p>The locator allows the application to determine the end |
|
* position of any document-related event, even if the parser is |
|
* not reporting an error. Typically, the application will |
|
* use this information for reporting its own errors (such as |
|
* character content that does not match an application's |
|
* business rules). The information returned by the locator |
|
* is probably not sufficient for use with a search engine.</p> |
|
* |
|
* <p>Note that the locator will return correct information only |
|
* during the invocation of the events in this interface. The |
|
* application should not attempt to use it at any other time.</p> |
|
* |
|
* @param locator An object that can return the location of |
|
* any SAX document event. |
|
* @see org.xml.sax.Locator |
|
*/ |
|
public abstract void setDocumentLocator (Locator locator); |
|
/** |
|
* Receive notification of the beginning of a document. |
|
* |
|
* <p>The SAX parser will invoke this method only once, before any |
|
* other methods in this interface or in DTDHandler (except for |
|
* setDocumentLocator).</p> |
|
* |
|
* @throws org.xml.sax.SAXException Any SAX exception, possibly |
|
* wrapping another exception. |
|
*/ |
|
public abstract void startDocument () |
|
throws SAXException; |
|
/** |
|
* Receive notification of the end of a document. |
|
* |
|
* <p>The SAX parser will invoke this method only once, and it will |
|
* be the last method invoked during the parse. The parser shall |
|
* not invoke this method until it has either abandoned parsing |
|
* (because of an unrecoverable error) or reached the end of |
|
* input.</p> |
|
* |
|
* @throws org.xml.sax.SAXException Any SAX exception, possibly |
|
* wrapping another exception. |
|
*/ |
|
public abstract void endDocument () |
|
throws SAXException; |
|
/** |
|
* Receive notification of the beginning of an element. |
|
* |
|
* <p>The Parser will invoke this method at the beginning of every |
|
* element in the XML document; there will be a corresponding |
|
* endElement() event for every startElement() event (even when the |
|
* element is empty). All of the element's content will be |
|
* reported, in order, before the corresponding endElement() |
|
* event.</p> |
|
* |
|
* <p>If the element name has a namespace prefix, the prefix will |
|
* still be attached. Note that the attribute list provided will |
|
* contain only attributes with explicit values (specified or |
|
* defaulted): #IMPLIED attributes will be omitted.</p> |
|
* |
|
* @param name The element type name. |
|
* @param atts The attributes attached to the element, if any. |
|
* @throws org.xml.sax.SAXException Any SAX exception, possibly |
|
* wrapping another exception. |
|
* @see #endElement |
|
* @see org.xml.sax.AttributeList |
|
*/ |
|
public abstract void startElement (String name, AttributeList atts) |
|
throws SAXException; |
|
/** |
|
* Receive notification of the end of an element. |
|
* |
|
* <p>The SAX parser will invoke this method at the end of every |
|
* element in the XML document; there will be a corresponding |
|
* startElement() event for every endElement() event (even when the |
|
* element is empty).</p> |
|
* |
|
* <p>If the element name has a namespace prefix, the prefix will |
|
* still be attached to the name.</p> |
|
* |
|
* @param name The element type name |
|
* @throws org.xml.sax.SAXException Any SAX exception, possibly |
|
* wrapping another exception. |
|
*/ |
|
public abstract void endElement (String name) |
|
throws SAXException; |
|
/** |
|
* Receive notification of character data. |
|
* |
|
* <p>The Parser will call this method to report each chunk of |
|
* character data. SAX parsers may return all contiguous character |
|
* data in a single chunk, or they may split it into several |
|
* chunks; however, all of the characters in any single event |
|
* must come from the same external entity, so that the Locator |
|
* provides useful information.</p> |
|
* |
|
* <p>The application must not attempt to read from the array |
|
* outside of the specified range.</p> |
|
* |
|
* <p>Note that some parsers will report whitespace using the |
|
* ignorableWhitespace() method rather than this one (validating |
|
* parsers must do so).</p> |
|
* |
|
* @param ch The characters from the XML document. |
|
* @param start The start position in the array. |
|
* @param length The number of characters to read from the array. |
|
* @throws org.xml.sax.SAXException Any SAX exception, possibly |
|
* wrapping another exception. |
|
* @see #ignorableWhitespace |
|
* @see org.xml.sax.Locator |
|
*/ |
|
public abstract void characters (char ch[], int start, int length) |
|
throws SAXException; |
|
/** |
|
* Receive notification of ignorable whitespace in element content. |
|
* |
|
* <p>Validating Parsers must use this method to report each chunk |
|
* of ignorable whitespace (see the W3C XML 1.0 recommendation, |
|
* section 2.10): non-validating parsers may also use this method |
|
* if they are capable of parsing and using content models.</p> |
|
* |
|
* <p>SAX parsers may return all contiguous whitespace in a single |
|
* chunk, or they may split it into several chunks; however, all of |
|
* the characters in any single event must come from the same |
|
* external entity, so that the Locator provides useful |
|
* information.</p> |
|
* |
|
* <p>The application must not attempt to read from the array |
|
* outside of the specified range.</p> |
|
* |
|
* @param ch The characters from the XML document. |
|
* @param start The start position in the array. |
|
* @param length The number of characters to read from the array. |
|
* @throws org.xml.sax.SAXException Any SAX exception, possibly |
|
* wrapping another exception. |
|
* @see #characters |
|
*/ |
|
public abstract void ignorableWhitespace (char ch[], int start, int length) |
|
throws SAXException; |
|
/** |
|
* Receive notification of a processing instruction. |
|
* |
|
* <p>The Parser will invoke this method once for each processing |
|
* instruction found: note that processing instructions may occur |
|
* before or after the main document element.</p> |
|
* |
|
* <p>A SAX parser should never report an XML declaration (XML 1.0, |
|
* section 2.8) or a text declaration (XML 1.0, section 4.3.1) |
|
* using this method.</p> |
|
* |
|
* @param target The processing instruction target. |
|
* @param data The processing instruction data, or null if |
|
* none was supplied. |
|
* @throws org.xml.sax.SAXException Any SAX exception, possibly |
|
* wrapping another exception. |
|
*/ |
|
public abstract void processingInstruction (String target, String data) |
|
throws SAXException; |
|
} |
|
// end of DocumentHandler.java |