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