001// ContentHandler.java - handle main document content. 002// Written by David Megginson, sax@megginson.com 003// NO WARRANTY! This class is in the public domain. 004 005// $Id: ContentHandler.java,v 1.1 2001/03/05 21:40:05 jstrachan Exp $ 006 007package org.xml.sax; 008 009 010/** 011 * Receive notification of the logical content of a document. 012 * 013 * <blockquote> 014 * <em>This module, both source code and documentation, is in the 015 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 016 * </blockquote> 017 * 018 * <p>This is the main interface that most SAX applications 019 * implement: if the application needs to be informed of basic parsing 020 * events, it implements this interface and registers an instance with 021 * the SAX parser using the {@link org.xml.sax.XMLReader#setContentHandler 022 * setContentHandler} method. The parser uses the instance to report 023 * basic document-related events like the start and end of elements 024 * and character data.</p> 025 * 026 * <p>The order of events in this interface is very important, and 027 * mirrors the order of information in the document itself. For 028 * example, all of an element's content (character data, processing 029 * instructions, and/or subelements) will appear, in order, between 030 * the startElement event and the corresponding endElement event.</p> 031 * 032 * <p>This interface is similar to the now-deprecated SAX 1.0 033 * DocumentHandler interface, but it adds support for Namespaces 034 * and for reporting skipped entities (in non-validating XML 035 * processors).</p> 036 * 037 * <p>Implementors should note that there is also a Java class 038 * {@link java.net.ContentHandler ContentHandler} in the java.net 039 * package; that means that it's probably a bad idea to do</p> 040 * 041 * <blockquote> 042 * import java.net.*; 043 * import org.xml.sax.*; 044 * </blockquote> 045 * 046 * <p>In fact, "import ...*" is usually a sign of sloppy programming 047 * anyway, so the user should consider this a feature rather than a 048 * bug.</p> 049 * 050 * @since SAX 2.0 051 * @author David Megginson, 052 * <a href="mailto:sax@megginson.com">sax@megginson.com</a> 053 * @version 2.0 054 * @see org.xml.sax.XMLReader 055 * @see org.xml.sax.DTDHandler 056 * @see org.xml.sax.ErrorHandler 057 */ 058public interface ContentHandler 059{ 060 061 /** 062 * Receive an object for locating the origin of SAX document events. 063 * 064 * <p>SAX parsers are strongly encouraged (though not absolutely 065 * required) to supply a locator: if it does so, it must supply 066 * the locator to the application by invoking this method before 067 * invoking any of the other methods in the ContentHandler 068 * interface.</p> 069 * 070 * <p>The locator allows the application to determine the end 071 * position of any document-related event, even if the parser is 072 * not reporting an error. Typically, the application will 073 * use this information for reporting its own errors (such as 074 * character content that does not match an application's 075 * business rules). The information returned by the locator 076 * is probably not sufficient for use with a search engine.</p> 077 * 078 * <p>Note that the locator will return correct information only 079 * during the invocation of the events in this interface. The 080 * application should not attempt to use it at any other time.</p> 081 * 082 * @param locator An object that can return the location of 083 * any SAX document event. 084 * @see org.xml.sax.Locator 085 */ 086 public void setDocumentLocator (Locator locator); 087 088 089 /** 090 * Receive notification of the beginning of a document. 091 * 092 * <p>The SAX parser will invoke this method only once, before any 093 * other methods in this interface or in {@link org.xml.sax.DTDHandler 094 * DTDHandler} (except for {@link #setDocumentLocator 095 * setDocumentLocator}).</p> 096 * 097 * @exception org.xml.sax.SAXException Any SAX exception, possibly 098 * wrapping another exception. 099 * @see #endDocument 100 */ 101 public void startDocument () 102 throws SAXException; 103 104 105 /** 106 * Receive notification of the end of a document. 107 * 108 * <p>The SAX parser will invoke this method only once, and it will 109 * be the last method invoked during the parse. The parser shall 110 * not invoke this method until it has either abandoned parsing 111 * (because of an unrecoverable error) or reached the end of 112 * input.</p> 113 * 114 * @exception org.xml.sax.SAXException Any SAX exception, possibly 115 * wrapping another exception. 116 * @see #startDocument 117 */ 118 public void endDocument() 119 throws SAXException; 120 121 122 /** 123 * Begin the scope of a prefix-URI Namespace mapping. 124 * 125 * <p>The information from this event is not necessary for 126 * normal Namespace processing: the SAX XML reader will 127 * automatically replace prefixes for element and attribute 128 * names when the <code>http://xml.org/sax/features/namespaces</code> 129 * feature is <var>true</var> (the default).</p> 130 * 131 * <p>There are cases, however, when applications need to 132 * use prefixes in character data or in attribute values, 133 * where they cannot safely be expanded automatically; the 134 * start/endPrefixMapping event supplies the information 135 * to the application to expand prefixes in those contexts 136 * itself, if necessary.</p> 137 * 138 * <p>Note that start/endPrefixMapping events are not 139 * guaranteed to be properly nested relative to each-other: 140 * all startPrefixMapping events will occur before the 141 * corresponding {@link #startElement startElement} event, 142 * and all {@link #endPrefixMapping endPrefixMapping} 143 * events will occur after the corresponding {@link #endElement 144 * endElement} event, but their order is not otherwise 145 * guaranteed.</p> 146 * 147 * <p>There should never be start/endPrefixMapping events for the 148 * "xml" prefix, since it is predeclared and immutable.</p> 149 * 150 * @param prefix The Namespace prefix being declared. 151 * @param uri The Namespace URI the prefix is mapped to. 152 * @exception org.xml.sax.SAXException The client may throw 153 * an exception during processing. 154 * @see #endPrefixMapping 155 * @see #startElement 156 */ 157 public void startPrefixMapping (String prefix, String uri) 158 throws SAXException; 159 160 161 /** 162 * End the scope of a prefix-URI mapping. 163 * 164 * <p>See {@link #startPrefixMapping startPrefixMapping} for 165 * details. This event will always occur after the corresponding 166 * {@link #endElement endElement} event, but the order of 167 * {@link #endPrefixMapping endPrefixMapping} events is not otherwise 168 * guaranteed.</p> 169 * 170 * @param prefix The prefix that was being mapping. 171 * @exception org.xml.sax.SAXException The client may throw 172 * an exception during processing. 173 * @see #startPrefixMapping 174 * @see #endElement 175 */ 176 public void endPrefixMapping (String prefix) 177 throws SAXException; 178 179 180 /** 181 * Receive notification of the beginning of an element. 182 * 183 * <p>The Parser will invoke this method at the beginning of every 184 * element in the XML document; there will be a corresponding 185 * {@link #endElement endElement} event for every startElement event 186 * (even when the element is empty). All of the element's content will be 187 * reported, in order, before the corresponding endElement 188 * event.</p> 189 * 190 * <p>This event allows up to three name components for each 191 * element:</p> 192 * 193 * <ol> 194 * <li>the Namespace URI;</li> 195 * <li>the local name; and</li> 196 * <li>the qualified (prefixed) name.</li> 197 * </ol> 198 * 199 * <p>Any or all of these may be provided, depending on the 200 * values of the <var>http://xml.org/sax/features/namespaces</var> 201 * and the <var>http://xml.org/sax/features/namespace-prefixes</var> 202 * properties:</p> 203 * 204 * <ul> 205 * <li>the Namespace URI and local name are required when 206 * the namespaces property is <var>true</var> (the default), and are 207 * optional when the namespaces property is <var>false</var> (if one is 208 * specified, both must be);</li> 209 * <li>the qualified name is required when the namespace-prefixes property 210 * is <var>true</var>, and is optional when the namespace-prefixes property 211 * is <var>false</var> (the default).</li> 212 * </ul> 213 * 214 * <p>Note that the attribute list provided will contain only 215 * attributes with explicit values (specified or defaulted): 216 * #IMPLIED attributes will be omitted. The attribute list 217 * will contain attributes used for Namespace declarations 218 * (xmlns* attributes) only if the 219 * <code>http://xml.org/sax/features/namespace-prefixes</code> 220 * property is true (it is false by default, and support for a 221 * true value is optional).</p> 222 * 223 * @param uri The Namespace URI, or the empty string if the 224 * element has no Namespace URI or if Namespace 225 * processing is not being performed. 226 * @param localName The local name (without prefix), or the 227 * empty string if Namespace processing is not being 228 * performed. 229 * @param qName The qualified name (with prefix), or the 230 * empty string if qualified names are not available. 231 * @param atts The attributes attached to the element. If 232 * there are no attributes, it shall be an empty 233 * Attributes object. 234 * @exception org.xml.sax.SAXException Any SAX exception, possibly 235 * wrapping another exception. 236 * @see #endElement 237 * @see org.xml.sax.Attributes 238 */ 239 public void startElement (String namespaceURI, String localName, 240 String qName, Attributes atts) 241 throws SAXException; 242 243 244 /** 245 * Receive notification of the end of an element. 246 * 247 * <p>The SAX parser will invoke this method at the end of every 248 * element in the XML document; there will be a corresponding 249 * {@link #startElement startElement} event for every endElement 250 * event (even when the element is empty).</p> 251 * 252 * <p>For information on the names, see startElement.</p> 253 * 254 * @param uri The Namespace URI, or the empty string if the 255 * element has no Namespace URI or if Namespace 256 * processing is not being performed. 257 * @param localName The local name (without prefix), or the 258 * empty string if Namespace processing is not being 259 * performed. 260 * @param qName The qualified XML 1.0 name (with prefix), or the 261 * empty string if qualified names are not available. 262 * @exception org.xml.sax.SAXException Any SAX exception, possibly 263 * wrapping another exception. 264 */ 265 public void endElement (String namespaceURI, String localName, 266 String qName) 267 throws SAXException; 268 269 270 /** 271 * Receive notification of character data. 272 * 273 * <p>The Parser will call this method to report each chunk of 274 * character data. SAX parsers may return all contiguous character 275 * data in a single chunk, or they may split it into several 276 * chunks; however, all of the characters in any single event 277 * must come from the same external entity so that the Locator 278 * provides useful information.</p> 279 * 280 * <p>The application must not attempt to read from the array 281 * outside of the specified range.</p> 282 * 283 * <p>Note that some parsers will report whitespace in element 284 * content using the {@link #ignorableWhitespace ignorableWhitespace} 285 * method rather than this one (validating parsers <em>must</em> 286 * do so).</p> 287 * 288 * @param ch The characters from the XML document. 289 * @param start The start position in the array. 290 * @param length The number of characters to read from the array. 291 * @exception org.xml.sax.SAXException Any SAX exception, possibly 292 * wrapping another exception. 293 * @see #ignorableWhitespace 294 * @see org.xml.sax.Locator 295 */ 296 public void characters (char ch[], int start, int length) 297 throws SAXException; 298 299 300 /** 301 * Receive notification of ignorable whitespace in element content. 302 * 303 * <p>Validating Parsers must use this method to report each chunk 304 * of whitespace in element content (see the W3C XML 1.0 recommendation, 305 * section 2.10): non-validating parsers may also use this method 306 * if they are capable of parsing and using content models.</p> 307 * 308 * <p>SAX parsers may return all contiguous whitespace in a single 309 * chunk, or they may split it into several chunks; however, all of 310 * the characters in any single event must come from the same 311 * external entity, so that the Locator provides useful 312 * information.</p> 313 * 314 * <p>The application must not attempt to read from the array 315 * outside of the specified range.</p> 316 * 317 * @param ch The characters from the XML document. 318 * @param start The start position in the array. 319 * @param length The number of characters to read from the array. 320 * @exception org.xml.sax.SAXException Any SAX exception, possibly 321 * wrapping another exception. 322 * @see #characters 323 */ 324 public void ignorableWhitespace (char ch[], int start, int length) 325 throws SAXException; 326 327 328 /** 329 * Receive notification of a processing instruction. 330 * 331 * <p>The Parser will invoke this method once for each processing 332 * instruction found: note that processing instructions may occur 333 * before or after the main document element.</p> 334 * 335 * <p>A SAX parser must never report an XML declaration (XML 1.0, 336 * section 2.8) or a text declaration (XML 1.0, section 4.3.1) 337 * using this method.</p> 338 * 339 * @param target The processing instruction target. 340 * @param data The processing instruction data, or null if 341 * none was supplied. The data does not include any 342 * whitespace separating it from the target. 343 * @exception org.xml.sax.SAXException Any SAX exception, possibly 344 * wrapping another exception. 345 */ 346 public void processingInstruction (String target, String data) 347 throws SAXException; 348 349 350 /** 351 * Receive notification of a skipped entity. 352 * 353 * <p>The Parser will invoke this method once for each entity 354 * skipped. Non-validating processors may skip entities if they 355 * have not seen the declarations (because, for example, the 356 * entity was declared in an external DTD subset). All processors 357 * may skip external entities, depending on the values of the 358 * <code>http://xml.org/sax/features/external-general-entities</code> 359 * and the 360 * <code>http://xml.org/sax/features/external-parameter-entities</code> 361 * properties.</p> 362 * 363 * @param name The name of the skipped entity. If it is a 364 * parameter entity, the name will begin with '%', and if 365 * it is the external DTD subset, it will be the string 366 * "[dtd]". 367 * @exception org.xml.sax.SAXException Any SAX exception, possibly 368 * wrapping another exception. 369 */ 370 public void skippedEntity (String name) 371 throws SAXException; 372} 373 374// end of ContentHandler.java