unused/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.9 2004/04/26 17:34:35 dmegginson 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     @Override
  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     @Override
 119                 public void notationDecl (String name, String publicId, String systemId)
 120         throws SAXException
 121     {
 122         // no op
 123     }
 124
 125
 126     /**
 127      * Receive notification of an unparsed entity declaration.
 128      *
 129      * <p>By default, do nothing.  Application writers may override this
 130      * method in a subclass to keep track of the unparsed entities
 131      * declared in a document.</p>
 132      *
 133      * @param name The entity name.
 134      * @param publicId The entity public identifier, or null if not
 135      *                 available.
 136      * @param systemId The entity system identifier.
 137      * @param notationName The name of the associated notation.
 138      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 139      *            wrapping another exception.
 140      * @see org.xml.sax.DTDHandler#unparsedEntityDecl
 141      */
 142     @Override
 143                 public void unparsedEntityDecl (String name, String publicId,
 144                                     String systemId, String notationName)
 145         throws SAXException
 146     {
 147         // no op
 148     }
 149
 150
 151 \f
 152     ////////////////////////////////////////////////////////////////////
 153     // Default implementation of ContentHandler interface.
 154     ////////////////////////////////////////////////////////////////////
 155
 156
 157     /**
 158      * Receive a Locator object for document events.
 159      *
 160      * <p>By default, do nothing.  Application writers may override this
 161      * method in a subclass if they wish to store the locator for use
 162      * with other document events.</p>
 163      *
 164      * @param locator A locator for all SAX document events.
 165      * @see org.xml.sax.ContentHandler#setDocumentLocator
 166      * @see org.xml.sax.Locator
 167      */
 168     @Override
 169                 public void setDocumentLocator (Locator locator)
 170     {
 171         // no op
 172     }
 173
 174
 175     /**
 176      * Receive notification of the beginning of the document.
 177      *
 178      * <p>By default, do nothing.  Application writers may override this
 179      * method in a subclass to take specific actions at the beginning
 180      * of a document (such as allocating the root node of a tree or
 181      * creating an output file).</p>
 182      *
 183      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 184      *            wrapping another exception.
 185      * @see org.xml.sax.ContentHandler#startDocument
 186      */
 187     @Override
 188                 public void startDocument ()
 189         throws SAXException
 190     {
 191         // no op
 192     }
 193
 194
 195     /**
 196      * Receive notification of the end of the document.
 197      *
 198      * <p>By default, do nothing.  Application writers may override this
 199      * method in a subclass to take specific actions at the end
 200      * of a document (such as finalising a tree or closing an output
 201      * file).</p>
 202      *
 203      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 204      *            wrapping another exception.
 205      * @see org.xml.sax.ContentHandler#endDocument
 206      */
 207     @Override
 208                 public void endDocument ()
 209         throws SAXException
 210     {
 211         // no op
 212     }
 213
 214
 215     /**
 216      * Receive notification of the start of a Namespace mapping.
 217      *
 218      * <p>By default, do nothing.  Application writers may override this
 219      * method in a subclass to take specific actions at the start of
 220      * each Namespace prefix scope (such as storing the prefix mapping).</p>
 221      *
 222      * @param prefix The Namespace prefix being declared.
 223      * @param uri The Namespace URI mapped to the prefix.
 224      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 225      *            wrapping another exception.
 226      * @see org.xml.sax.ContentHandler#startPrefixMapping
 227      */
 228     @Override
 229                 public void startPrefixMapping (String prefix, String uri)
 230         throws SAXException
 231     {
 232         // no op
 233     }
 234
 235
 236     /**
 237      * Receive notification of the end of a Namespace mapping.
 238      *
 239      * <p>By default, do nothing.  Application writers may override this
 240      * method in a subclass to take specific actions at the end of
 241      * each prefix mapping.</p>
 242      *
 243      * @param prefix The Namespace prefix being declared.
 244      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 245      *            wrapping another exception.
 246      * @see org.xml.sax.ContentHandler#endPrefixMapping
 247      */
 248     @Override
 249                 public void endPrefixMapping (String prefix)
 250         throws SAXException
 251     {
 252         // no op
 253     }
 254
 255
 256     /**
 257      * Receive notification of the start of an element.
 258      *
 259      * <p>By default, do nothing.  Application writers may override this
 260      * method in a subclass to take specific actions at the start of
 261      * each element (such as allocating a new tree node or writing
 262      * output to a file).</p>
 263      *
 264      * @param uri The Namespace URI, or the empty string if the
 265      *        element has no Namespace URI or if Namespace
 266      *        processing is not being performed.
 267      * @param localName The local name (without prefix), or the
 268      *        empty string if Namespace processing is not being
 269      *        performed.
 270      * @param qName The qualified name (with prefix), or the
 271      *        empty string if qualified names are not available.
 272      * @param attributes The attributes attached to the element.  If
 273      *        there are no attributes, it shall be an empty
 274      *        Attributes object.
 275      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 276      *            wrapping another exception.
 277      * @see org.xml.sax.ContentHandler#startElement
 278      */
 279     @Override
 280                 public void startElement (String uri, String localName,
 281                               String qName, Attributes attributes)
 282         throws SAXException
 283     {
 284         // no op
 285     }
 286
 287
 288     /**
 289      * Receive notification of the end of an element.
 290      *
 291      * <p>By default, do nothing.  Application writers may override this
 292      * method in a subclass to take specific actions at the end of
 293      * each element (such as finalising a tree node or writing
 294      * output to a file).</p>
 295      *
 296      * @param uri The Namespace URI, or the empty string if the
 297      *        element has no Namespace URI or if Namespace
 298      *        processing is not being performed.
 299      * @param localName The local name (without prefix), or the
 300      *        empty string if Namespace processing is not being
 301      *        performed.
 302      * @param qName The qualified name (with prefix), or the
 303      *        empty string if qualified names are not available.
 304      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 305      *            wrapping another exception.
 306      * @see org.xml.sax.ContentHandler#endElement
 307      */
 308     @Override
 309                 public void endElement (String uri, String localName, String qName)
 310         throws SAXException
 311     {
 312         // no op
 313     }
 314
 315
 316     /**
 317      * Receive notification of character data inside an element.
 318      *
 319      * <p>By default, do nothing.  Application writers may override this
 320      * method to take specific actions for each chunk of character data
 321      * (such as adding the data to a node or buffer, or printing it to
 322      * a file).</p>
 323      *
 324      * @param ch The characters.
 325      * @param start The start position in the character array.
 326      * @param length The number of characters to use from the
 327      *               character array.
 328      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 329      *            wrapping another exception.
 330      * @see org.xml.sax.ContentHandler#characters
 331      */
 332     @Override
 333                 public void characters (char ch[], int start, int length)
 334         throws SAXException
 335     {
 336         // no op
 337     }
 338
 339
 340     /**
 341      * Receive notification of ignorable whitespace in element content.
 342      *
 343      * <p>By default, do nothing.  Application writers may override this
 344      * method to take specific actions for each chunk of ignorable
 345      * whitespace (such as adding data to a node or buffer, or printing
 346      * it to a file).</p>
 347      *
 348      * @param ch The whitespace characters.
 349      * @param start The start position in the character array.
 350      * @param length The number of characters to use from the
 351      *               character array.
 352      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 353      *            wrapping another exception.
 354      * @see org.xml.sax.ContentHandler#ignorableWhitespace
 355      */
 356     @Override
 357                 public void ignorableWhitespace (char ch[], int start, int length)
 358         throws SAXException
 359     {
 360         // no op
 361     }
 362
 363
 364     /**
 365      * Receive notification of a processing instruction.
 366      *
 367      * <p>By default, do nothing.  Application writers may override this
 368      * method in a subclass to take specific actions for each
 369      * processing instruction, such as setting status variables or
 370      * invoking other methods.</p>
 371      *
 372      * @param target The processing instruction target.
 373      * @param data The processing instruction data, or null if
 374      *             none is supplied.
 375      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 376      *            wrapping another exception.
 377      * @see org.xml.sax.ContentHandler#processingInstruction
 378      */
 379     @Override
 380                 public void processingInstruction (String target, String data)
 381         throws SAXException
 382     {
 383         // no op
 384     }
 385
 386
 387     /**
 388      * Receive notification of a skipped entity.
 389      *
 390      * <p>By default, do nothing.  Application writers may override this
 391      * method in a subclass to take specific actions for each
 392      * processing instruction, such as setting status variables or
 393      * invoking other methods.</p>
 394      *
 395      * @param name The name of the skipped entity.
 396      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 397      *            wrapping another exception.
 398      * @see org.xml.sax.ContentHandler#processingInstruction
 399      */
 400     @Override
 401                 public void skippedEntity (String name)
 402         throws SAXException
 403     {
 404         // no op
 405     }
 406
 407
 408 \f
 409     ////////////////////////////////////////////////////////////////////
 410     // Default implementation of the ErrorHandler interface.
 411     ////////////////////////////////////////////////////////////////////
 412
 413
 414     /**
 415      * Receive notification of a parser warning.
 416      *
 417      * <p>The default implementation does nothing.  Application writers
 418      * may override this method in a subclass to take specific actions
 419      * for each warning, such as inserting the message in a log file or
 420      * printing it to the console.</p>
 421      *
 422      * @param e The warning information encoded as an exception.
 423      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 424      *            wrapping another exception.
 425      * @see org.xml.sax.ErrorHandler#warning
 426      * @see org.xml.sax.SAXParseException
 427      */
 428     @Override
 429                 public void warning (SAXParseException e)
 430         throws SAXException
 431     {
 432         // no op
 433     }
 434
 435
 436     /**
 437      * Receive notification of a recoverable parser error.
 438      *
 439      * <p>The default implementation does nothing.  Application writers
 440      * may override this method in a subclass to take specific actions
 441      * for each error, such as inserting the message in a log file or
 442      * printing it to the console.</p>
 443      *
 444      * @param e The warning information encoded as an exception.
 445      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 446      *            wrapping another exception.
 447      * @see org.xml.sax.ErrorHandler#warning
 448      * @see org.xml.sax.SAXParseException
 449      */
 450     @Override
 451                 public void error (SAXParseException e)
 452         throws SAXException
 453     {
 454         // no op
 455     }
 456
 457
 458     /**
 459      * Report a fatal XML parsing error.
 460      *
 461      * <p>The default implementation throws a SAXParseException.
 462      * Application writers may override this method in a subclass if
 463      * they need to take specific actions for each fatal error (such as
 464      * collecting all of the errors into a single report): in any case,
 465      * the application must stop all regular processing when this
 466      * method is invoked, since the document is no longer reliable, and
 467      * the parser may no longer report parsing events.</p>
 468      *
 469      * @param e The error information encoded as an exception.
 470      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 471      *            wrapping another exception.
 472      * @see org.xml.sax.ErrorHandler#fatalError
 473      * @see org.xml.sax.SAXParseException
 474      */
 475     @Override
 476                 public void fatalError (SAXParseException e)
 477         throws SAXException
 478     {
 479         throw e;
 480     }
 481
 482 }
 483
 484 // end of DefaultHandler.java