001// SAX document handler. 002// http://www.saxproject.org 003// No warranty; no copyright -- use this as you will. 004// $Id: DocumentHandler.java,v 1.1 2004/12/23 22:38:42 mark Exp $ 005 006package org.xml.sax; 007 008/** 009 * Receive notification of general document events. 010 * 011 * <blockquote> 012 * <em>This module, both source code and documentation, is in the 013 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 014 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> 015 * for further information. 016 * </blockquote> 017 * 018 * <p>This was the main event-handling interface for SAX1; in 019 * SAX2, it has been replaced by {@link org.xml.sax.ContentHandler 020 * ContentHandler}, which provides Namespace support and reporting 021 * of skipped entities. This interface is included in SAX2 only 022 * to support legacy SAX1 applications.</p> 023 * 024 * <p>The order of events in this interface is very important, and 025 * mirrors the order of information in the document itself. For 026 * example, all of an element's content (character data, processing 027 * instructions, and/or subelements) will appear, in order, between 028 * the startElement event and the corresponding endElement event.</p> 029 * 030 * <p>Application writers who do not want to implement the entire 031 * interface can derive a class from HandlerBase, which implements 032 * the default functionality; parser writers can instantiate 033 * HandlerBase to obtain a default handler. The application can find 034 * the location of any document event using the Locator interface 035 * supplied by the Parser through the setDocumentLocator method.</p> 036 * 037 * @deprecated This interface has been replaced by the SAX2 038 * {@link org.xml.sax.ContentHandler ContentHandler} 039 * interface, which includes Namespace support. 040 * @since SAX 1.0 041 * @author David Megginson 042 * @version 2.0.1 (sax2r2) 043 * @see org.xml.sax.Parser#setDocumentHandler 044 * @see org.xml.sax.Locator 045 * @see org.xml.sax.HandlerBase 046 */ 047public interface DocumentHandler { 048 049 050 /** 051 * Receive an object for locating the origin of SAX document events. 052 * 053 * <p>SAX parsers are strongly encouraged (though not absolutely 054 * required) to supply a locator: if it does so, it must supply 055 * the locator to the application by invoking this method before 056 * invoking any of the other methods in the DocumentHandler 057 * interface.</p> 058 * 059 * <p>The locator allows the application to determine the end 060 * position of any document-related event, even if the parser is 061 * not reporting an error. Typically, the application will 062 * use this information for reporting its own errors (such as 063 * character content that does not match an application's 064 * business rules). The information returned by the locator 065 * is probably not sufficient for use with a search engine.</p> 066 * 067 * <p>Note that the locator will return correct information only 068 * during the invocation of the events in this interface. The 069 * application should not attempt to use it at any other time.</p> 070 * 071 * @param locator An object that can return the location of 072 * any SAX document event. 073 * @see org.xml.sax.Locator 074 */ 075 public abstract void setDocumentLocator (Locator locator); 076 077 078 /** 079 * Receive notification of the beginning of a document. 080 * 081 * <p>The SAX parser will invoke this method only once, before any 082 * other methods in this interface or in DTDHandler (except for 083 * setDocumentLocator).</p> 084 * 085 * @exception org.xml.sax.SAXException Any SAX exception, possibly 086 * wrapping another exception. 087 */ 088 public abstract void startDocument () 089 throws SAXException; 090 091 092 /** 093 * Receive notification of the end of a document. 094 * 095 * <p>The SAX parser will invoke this method only once, and it will 096 * be the last method invoked during the parse. The parser shall 097 * not invoke this method until it has either abandoned parsing 098 * (because of an unrecoverable error) or reached the end of 099 * input.</p> 100 * 101 * @exception org.xml.sax.SAXException Any SAX exception, possibly 102 * wrapping another exception. 103 */ 104 public abstract void endDocument () 105 throws SAXException; 106 107 108 /** 109 * Receive notification of the beginning of an element. 110 * 111 * <p>The Parser will invoke this method at the beginning of every 112 * element in the XML document; there will be a corresponding 113 * endElement() event for every startElement() event (even when the 114 * element is empty). All of the element's content will be 115 * reported, in order, before the corresponding endElement() 116 * event.</p> 117 * 118 * <p>If the element name has a namespace prefix, the prefix will 119 * still be attached. Note that the attribute list provided will 120 * contain only attributes with explicit values (specified or 121 * defaulted): #IMPLIED attributes will be omitted.</p> 122 * 123 * @param name The element type name. 124 * @param atts The attributes attached to the element, if any. 125 * @exception org.xml.sax.SAXException Any SAX exception, possibly 126 * wrapping another exception. 127 * @see #endElement 128 * @see org.xml.sax.AttributeList 129 */ 130 public abstract void startElement (String name, AttributeList atts) 131 throws SAXException; 132 133 134 /** 135 * Receive notification of the end of an element. 136 * 137 * <p>The SAX parser will invoke this method at the end of every 138 * element in the XML document; there will be a corresponding 139 * startElement() event for every endElement() event (even when the 140 * element is empty).</p> 141 * 142 * <p>If the element name has a namespace prefix, the prefix will 143 * still be attached to the name.</p> 144 * 145 * @param name The element type name 146 * @exception org.xml.sax.SAXException Any SAX exception, possibly 147 * wrapping another exception. 148 */ 149 public abstract void endElement (String name) 150 throws SAXException; 151 152 153 /** 154 * Receive notification of character data. 155 * 156 * <p>The Parser will call this method to report each chunk of 157 * character data. SAX parsers may return all contiguous character 158 * data in a single chunk, or they may split it into several 159 * chunks; however, all of the characters in any single event 160 * must come from the same external entity, so that the Locator 161 * provides useful information.</p> 162 * 163 * <p>The application must not attempt to read from the array 164 * outside of the specified range.</p> 165 * 166 * <p>Note that some parsers will report whitespace using the 167 * ignorableWhitespace() method rather than this one (validating 168 * parsers must do so).</p> 169 * 170 * @param ch The characters from the XML document. 171 * @param start The start position in the array. 172 * @param length The number of characters to read from the array. 173 * @exception org.xml.sax.SAXException Any SAX exception, possibly 174 * wrapping another exception. 175 * @see #ignorableWhitespace 176 * @see org.xml.sax.Locator 177 */ 178 public abstract void characters (char ch[], int start, int length) 179 throws SAXException; 180 181 182 /** 183 * Receive notification of ignorable whitespace in element content. 184 * 185 * <p>Validating Parsers must use this method to report each chunk 186 * of ignorable whitespace (see the W3C XML 1.0 recommendation, 187 * section 2.10): non-validating parsers may also use this method 188 * if they are capable of parsing and using content models.</p> 189 * 190 * <p>SAX parsers may return all contiguous whitespace in a single 191 * chunk, or they may split it into several chunks; however, all of 192 * the characters in any single event must come from the same 193 * external entity, so that the Locator provides useful 194 * information.</p> 195 * 196 * <p>The application must not attempt to read from the array 197 * outside of the specified range.</p> 198 * 199 * @param ch The characters from the XML document. 200 * @param start The start position in the array. 201 * @param length The number of characters to read from the array. 202 * @exception org.xml.sax.SAXException Any SAX exception, possibly 203 * wrapping another exception. 204 * @see #characters 205 */ 206 public abstract void ignorableWhitespace (char ch[], int start, int length) 207 throws SAXException; 208 209 210 /** 211 * Receive notification of a processing instruction. 212 * 213 * <p>The Parser will invoke this method once for each processing 214 * instruction found: note that processing instructions may occur 215 * before or after the main document element.</p> 216 * 217 * <p>A SAX parser should never report an XML declaration (XML 1.0, 218 * section 2.8) or a text declaration (XML 1.0, section 4.3.1) 219 * using this method.</p> 220 * 221 * @param target The processing instruction target. 222 * @param data The processing instruction data, or null if 223 * none was supplied. 224 * @exception org.xml.sax.SAXException Any SAX exception, possibly 225 * wrapping another exception. 226 */ 227 public abstract void processingInstruction (String target, String data) 228 throws SAXException; 229 230} 231 232// end of DocumentHandler.java