libjava/org/xml/sax/helpers/DefaultHandler.java

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