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