1 // DefaultHandler.java - default implementation of the core handlers. 2 // http://www.saxproject.org 3 // Written by David Megginson 4 // NO WARRANTY! This class is in the public domain. 5 // $Id: DefaultHandler.java,v 1.9 2004/04/26 17:34:35 dmegginson Exp $ 6 7 package org.xml.sax.helpers; 8 9 import java.io.IOException; 10 import org.xml.sax.Attributes; 11 import org.xml.sax.ContentHandler; 12 import org.xml.sax.DTDHandler; 13 import org.xml.sax.EntityResolver; 14 import org.xml.sax.ErrorHandler; 15 import org.xml.sax.InputSource; 16 import org.xml.sax.Locator; 17 import org.xml.sax.SAXException; 18 import org.xml.sax.SAXParseException; 19 20 21 /** 22 * Default base class for SAX2 event handlers. 23 * 24 * <blockquote> 25 * <em>This module, both source code and documentation, is in the 26 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 27 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> 28 * for further information. 29 * </blockquote> 30 * 31 * <p>This class is available as a convenience base class for SAX2 32 * applications: it provides default implementations for all of the 33 * callbacks in the four core SAX2 handler classes:</p> 34 * 35 * <ul> 36 * <li>{@link org.xml.sax.EntityResolver EntityResolver}</li> 37 * <li>{@link org.xml.sax.DTDHandler DTDHandler}</li> 38 * <li>{@link org.xml.sax.ContentHandler ContentHandler}</li> 39 * <li>{@link org.xml.sax.ErrorHandler ErrorHandler}</li> 40 * </ul> 41 * 42 * <p>Application writers can extend this class when they need to 43 * implement only part of an interface; parser writers can 44 * instantiate this class to provide default handlers when the 45 * application has not supplied its own.</p> 46 * 47 * <p>This class replaces the deprecated SAX1 48 * {@link org.xml.sax.HandlerBase HandlerBase} class.</p> 49 * 50 * @since SAX 2.0 51 * @author David Megginson, 52 * @version 2.0.1 (sax2r2) 53 * @see org.xml.sax.EntityResolver 54 * @see org.xml.sax.DTDHandler 55 * @see org.xml.sax.ContentHandler 56 * @see org.xml.sax.ErrorHandler 57 */ 58 public class DefaultHandler 59 implements EntityResolver, DTDHandler, ContentHandler, ErrorHandler 60 { 61 62 63 //////////////////////////////////////////////////////////////////// 64 // Default implementation of the EntityResolver interface. 65 //////////////////////////////////////////////////////////////////// 66 67 /** 68 * Resolve an external entity. 69 * 70 * <p>Always return null, so that the parser will use the system 71 * identifier provided in the XML document. This method implements 72 * the SAX default behaviour: application writers can override it 73 * in a subclass to do special translations such as catalog lookups 74 * or URI redirection.</p> 75 * 76 * @param publicId The public identifier, or null if none is 77 * available. 78 * @param systemId The system identifier provided in the XML 79 * document. 80 * @return The new input source, or null to require the 81 * default behaviour. 82 * @exception java.io.IOException If there is an error setting 83 * up the new input source. 84 * @exception org.xml.sax.SAXException Any SAX exception, possibly 85 * wrapping another exception. 86 * @see org.xml.sax.EntityResolver#resolveEntity 87 */ resolveEntity(String publicId, String systemId)88 public InputSource resolveEntity (String publicId, String systemId) 89 throws IOException, SAXException 90 { 91 return null; 92 } 93 94 95 96 //////////////////////////////////////////////////////////////////// 97 // Default implementation of DTDHandler interface. 98 //////////////////////////////////////////////////////////////////// 99 100 101 /** 102 * Receive notification of a notation declaration. 103 * 104 * <p>By default, do nothing. Application writers may override this 105 * method in a subclass if they wish to keep track of the notations 106 * declared in a document.</p> 107 * 108 * @param name The notation name. 109 * @param publicId The notation public identifier, or null if not 110 * available. 111 * @param systemId The notation system identifier. 112 * @exception org.xml.sax.SAXException Any SAX exception, possibly 113 * wrapping another exception. 114 * @see org.xml.sax.DTDHandler#notationDecl 115 */ notationDecl(String name, String publicId, String systemId)116 public void notationDecl (String name, String publicId, String systemId) 117 throws SAXException 118 { 119 // no op 120 } 121 122 123 /** 124 * Receive notification of an unparsed entity declaration. 125 * 126 * <p>By default, do nothing. Application writers may override this 127 * method in a subclass to keep track of the unparsed entities 128 * declared in a document.</p> 129 * 130 * @param name The entity name. 131 * @param publicId The entity public identifier, or null if not 132 * available. 133 * @param systemId The entity system identifier. 134 * @param notationName The name of the associated notation. 135 * @exception org.xml.sax.SAXException Any SAX exception, possibly 136 * wrapping another exception. 137 * @see org.xml.sax.DTDHandler#unparsedEntityDecl 138 */ unparsedEntityDecl(String name, String publicId, String systemId, String notationName)139 public void unparsedEntityDecl (String name, String publicId, 140 String systemId, String notationName) 141 throws SAXException 142 { 143 // no op 144 } 145 146 147 148 //////////////////////////////////////////////////////////////////// 149 // Default implementation of ContentHandler interface. 150 //////////////////////////////////////////////////////////////////// 151 152 153 /** 154 * Receive a Locator object for document events. 155 * 156 * <p>By default, do nothing. Application writers may override this 157 * method in a subclass if they wish to store the locator for use 158 * with other document events.</p> 159 * 160 * @param locator A locator for all SAX document events. 161 * @see org.xml.sax.ContentHandler#setDocumentLocator 162 * @see org.xml.sax.Locator 163 */ setDocumentLocator(Locator locator)164 public void setDocumentLocator (Locator locator) 165 { 166 // no op 167 } 168 169 170 /** 171 * Receive notification of the beginning of the document. 172 * 173 * <p>By default, do nothing. Application writers may override this 174 * method in a subclass to take specific actions at the beginning 175 * of a document (such as allocating the root node of a tree or 176 * creating an output file).</p> 177 * 178 * @exception org.xml.sax.SAXException Any SAX exception, possibly 179 * wrapping another exception. 180 * @see org.xml.sax.ContentHandler#startDocument 181 */ startDocument()182 public void startDocument () 183 throws SAXException 184 { 185 // no op 186 } 187 188 189 /** 190 * Receive notification of the end of the document. 191 * 192 * <p>By default, do nothing. Application writers may override this 193 * method in a subclass to take specific actions at the end 194 * of a document (such as finalising a tree or closing an output 195 * file).</p> 196 * 197 * @exception org.xml.sax.SAXException Any SAX exception, possibly 198 * wrapping another exception. 199 * @see org.xml.sax.ContentHandler#endDocument 200 */ endDocument()201 public void endDocument () 202 throws SAXException 203 { 204 // no op 205 } 206 207 208 /** 209 * Receive notification of the start of a Namespace mapping. 210 * 211 * <p>By default, do nothing. Application writers may override this 212 * method in a subclass to take specific actions at the start of 213 * each Namespace prefix scope (such as storing the prefix mapping).</p> 214 * 215 * @param prefix The Namespace prefix being declared. 216 * @param uri The Namespace URI mapped to the prefix. 217 * @exception org.xml.sax.SAXException Any SAX exception, possibly 218 * wrapping another exception. 219 * @see org.xml.sax.ContentHandler#startPrefixMapping 220 */ startPrefixMapping(String prefix, String uri)221 public void startPrefixMapping (String prefix, String uri) 222 throws SAXException 223 { 224 // no op 225 } 226 227 228 /** 229 * Receive notification of the end of a Namespace mapping. 230 * 231 * <p>By default, do nothing. Application writers may override this 232 * method in a subclass to take specific actions at the end of 233 * each prefix mapping.</p> 234 * 235 * @param prefix The Namespace prefix being declared. 236 * @exception org.xml.sax.SAXException Any SAX exception, possibly 237 * wrapping another exception. 238 * @see org.xml.sax.ContentHandler#endPrefixMapping 239 */ endPrefixMapping(String prefix)240 public void endPrefixMapping (String prefix) 241 throws SAXException 242 { 243 // no op 244 } 245 246 247 /** 248 * Receive notification of the start of an element. 249 * 250 * <p>By default, do nothing. Application writers may override this 251 * method in a subclass to take specific actions at the start of 252 * each element (such as allocating a new tree node or writing 253 * output to a file).</p> 254 * 255 * @param uri The Namespace URI, or the empty string if the 256 * element has no Namespace URI or if Namespace 257 * processing is not being performed. 258 * @param localName The local name (without prefix), or the 259 * empty string if Namespace processing is not being 260 * performed. 261 * @param qName The qualified name (with prefix), or the 262 * empty string if qualified names are not available. 263 * @param attributes The attributes attached to the element. If 264 * there are no attributes, it shall be an empty 265 * Attributes object. 266 * @exception org.xml.sax.SAXException Any SAX exception, possibly 267 * wrapping another exception. 268 * @see org.xml.sax.ContentHandler#startElement 269 */ startElement(String uri, String localName, String qName, Attributes attributes)270 public void startElement (String uri, String localName, 271 String qName, Attributes attributes) 272 throws SAXException 273 { 274 // no op 275 } 276 277 278 /** 279 * Receive notification of the end of an element. 280 * 281 * <p>By default, do nothing. Application writers may override this 282 * method in a subclass to take specific actions at the end of 283 * each element (such as finalising a tree node or writing 284 * output to a file).</p> 285 * 286 * @param uri The Namespace URI, or the empty string if the 287 * element has no Namespace URI or if Namespace 288 * processing is not being performed. 289 * @param localName The local name (without prefix), or the 290 * empty string if Namespace processing is not being 291 * performed. 292 * @param qName The qualified name (with prefix), or the 293 * empty string if qualified names are not available. 294 * @exception org.xml.sax.SAXException Any SAX exception, possibly 295 * wrapping another exception. 296 * @see org.xml.sax.ContentHandler#endElement 297 */ endElement(String uri, String localName, String qName)298 public void endElement (String uri, String localName, String qName) 299 throws SAXException 300 { 301 // no op 302 } 303 304 305 /** 306 * Receive notification of character data inside an element. 307 * 308 * <p>By default, do nothing. Application writers may override this 309 * method to take specific actions for each chunk of character data 310 * (such as adding the data to a node or buffer, or printing it to 311 * a file).</p> 312 * 313 * @param ch The characters. 314 * @param start The start position in the character array. 315 * @param length The number of characters to use from the 316 * character array. 317 * @exception org.xml.sax.SAXException Any SAX exception, possibly 318 * wrapping another exception. 319 * @see org.xml.sax.ContentHandler#characters 320 */ characters(char ch[], int start, int length)321 public void characters (char ch[], int start, int length) 322 throws SAXException 323 { 324 // no op 325 } 326 327 328 /** 329 * Receive notification of ignorable whitespace in element content. 330 * 331 * <p>By default, do nothing. Application writers may override this 332 * method to take specific actions for each chunk of ignorable 333 * whitespace (such as adding data to a node or buffer, or printing 334 * it to a file).</p> 335 * 336 * @param ch The whitespace characters. 337 * @param start The start position in the character array. 338 * @param length The number of characters to use from the 339 * character array. 340 * @exception org.xml.sax.SAXException Any SAX exception, possibly 341 * wrapping another exception. 342 * @see org.xml.sax.ContentHandler#ignorableWhitespace 343 */ ignorableWhitespace(char ch[], int start, int length)344 public void ignorableWhitespace (char ch[], int start, int length) 345 throws SAXException 346 { 347 // no op 348 } 349 350 351 /** 352 * Receive notification of a processing instruction. 353 * 354 * <p>By default, do nothing. Application writers may override this 355 * method in a subclass to take specific actions for each 356 * processing instruction, such as setting status variables or 357 * invoking other methods.</p> 358 * 359 * @param target The processing instruction target. 360 * @param data The processing instruction data, or null if 361 * none is supplied. 362 * @exception org.xml.sax.SAXException Any SAX exception, possibly 363 * wrapping another exception. 364 * @see org.xml.sax.ContentHandler#processingInstruction 365 */ processingInstruction(String target, String data)366 public void processingInstruction (String target, String data) 367 throws SAXException 368 { 369 // no op 370 } 371 372 373 /** 374 * Receive notification of a skipped entity. 375 * 376 * <p>By default, do nothing. Application writers may override this 377 * method in a subclass to take specific actions for each 378 * processing instruction, such as setting status variables or 379 * invoking other methods.</p> 380 * 381 * @param name The name of the skipped entity. 382 * @exception org.xml.sax.SAXException Any SAX exception, possibly 383 * wrapping another exception. 384 * @see org.xml.sax.ContentHandler#processingInstruction 385 */ skippedEntity(String name)386 public void skippedEntity (String name) 387 throws SAXException 388 { 389 // no op 390 } 391 392 393 394 //////////////////////////////////////////////////////////////////// 395 // Default implementation of the ErrorHandler interface. 396 //////////////////////////////////////////////////////////////////// 397 398 399 /** 400 * Receive notification of a parser warning. 401 * 402 * <p>The default implementation does nothing. Application writers 403 * may override this method in a subclass to take specific actions 404 * for each warning, such as inserting the message in a log file or 405 * printing it to the console.</p> 406 * 407 * @param e The warning information encoded as an exception. 408 * @exception org.xml.sax.SAXException Any SAX exception, possibly 409 * wrapping another exception. 410 * @see org.xml.sax.ErrorHandler#warning 411 * @see org.xml.sax.SAXParseException 412 */ warning(SAXParseException e)413 public void warning (SAXParseException e) 414 throws SAXException 415 { 416 // no op 417 } 418 419 420 /** 421 * Receive notification of a recoverable parser error. 422 * 423 * <p>The default implementation does nothing. Application writers 424 * may override this method in a subclass to take specific actions 425 * for each error, such as inserting the message in a log file or 426 * printing it to the console.</p> 427 * 428 * @param e The warning information encoded as an exception. 429 * @exception org.xml.sax.SAXException Any SAX exception, possibly 430 * wrapping another exception. 431 * @see org.xml.sax.ErrorHandler#warning 432 * @see org.xml.sax.SAXParseException 433 */ error(SAXParseException e)434 public void error (SAXParseException e) 435 throws SAXException 436 { 437 // no op 438 } 439 440 441 /** 442 * Report a fatal XML parsing error. 443 * 444 * <p>The default implementation throws a SAXParseException. 445 * Application writers may override this method in a subclass if 446 * they need to take specific actions for each fatal error (such as 447 * collecting all of the errors into a single report): in any case, 448 * the application must stop all regular processing when this 449 * method is invoked, since the document is no longer reliable, and 450 * the parser may no longer report parsing events.</p> 451 * 452 * @param e The error information encoded as an exception. 453 * @exception org.xml.sax.SAXException Any SAX exception, possibly 454 * wrapping another exception. 455 * @see org.xml.sax.ErrorHandler#fatalError 456 * @see org.xml.sax.SAXParseException 457 */ fatalError(SAXParseException e)458 public void fatalError (SAXParseException e) 459 throws SAXException 460 { 461 throw e; 462 } 463 464 } 465 466 // end of DefaultHandler.java 467