libjava/classpath/external/sax/org/xml/sax/HandlerBase.java

   1 // SAX default handler base class.
   2 // http://www.saxproject.org
   3 // No warranty; no copyright -- use this as you will.
   4 // $Id: HandlerBase.java,v 1.10 2012/04/18 17:29:03 nickc Exp $
   5
   6 package org.xml.sax;
   7
   8 /**
   9  * Default base class for handlers.
  10  *
  11  * <blockquote>
  12  * <em>This module, both source code and documentation, is in the
  13  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  14  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
  15  * for further information.
  16  * </blockquote>
  17  *
  18  * <p>This class implements the default behaviour for four SAX1
  19  * interfaces: EntityResolver, DTDHandler, DocumentHandler,
  20  * and ErrorHandler.  It is now obsolete, but is included in SAX2 to
  21  * support legacy SAX1 applications.  SAX2 applications should use
  22  * the {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}
  23  * class instead.</p>
  24  *
  25  * <p>Application writers can extend this class when they need to
  26  * implement only part of an interface; parser writers can
  27  * instantiate this class to provide default handlers when the
  28  * application has not supplied its own.</p>
  29  *
  30  * <p>Note that the use of this class is optional.</p>
  31  *
  32  * @deprecated This class works with the deprecated
  33  *             {@link org.xml.sax.DocumentHandler DocumentHandler}
  34  *             interface.  It has been replaced by the SAX2
  35  *             {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}
  36  *             class.
  37  * @since SAX 1.0
  38  * @author David Megginson
  39  * @version 2.0.1 (sax2r2)
  40  * @see org.xml.sax.EntityResolver
  41  * @see org.xml.sax.DTDHandler
  42  * @see org.xml.sax.DocumentHandler
  43  * @see org.xml.sax.ErrorHandler
  44  */
  45 public class HandlerBase
  46     implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler
  47 {
  48
  49
  50     ////////////////////////////////////////////////////////////////////
  51     // Default implementation of the EntityResolver interface.
  52     ////////////////////////////////////////////////////////////////////
  53
  54     /**
  55      * Resolve an external entity.
  56      *
  57      * <p>Always return null, so that the parser will use the system
  58      * identifier provided in the XML document.  This method implements
  59      * the SAX default behaviour: application writers can override it
  60      * in a subclass to do special translations such as catalog lookups
  61      * or URI redirection.</p>
  62      *
  63      * @param publicId The public identifer, or null if none is
  64      *                 available.
  65      * @param systemId The system identifier provided in the XML
  66      *                 document.
  67      * @return The new input source, or null to require the
  68      *         default behaviour.
  69      * @exception org.xml.sax.SAXException Any SAX exception, possibly
  70      *            wrapping another exception.
  71      * @see org.xml.sax.EntityResolver#resolveEntity
  72      */
  73     public InputSource resolveEntity (String publicId, String systemId)
  74         throws SAXException
  75     {
  76         return null;
  77     }
  78
  79
  80
  81     ////////////////////////////////////////////////////////////////////
  82     // Default implementation of DTDHandler interface.
  83     ////////////////////////////////////////////////////////////////////
  84
  85
  86     /**
  87      * Receive notification of a notation declaration.
  88      *
  89      * <p>By default, do nothing.  Application writers may override this
  90      * method in a subclass if they wish to keep track of the notations
  91      * declared in a document.</p>
  92      *
  93      * @param name The notation name.
  94      * @param publicId The notation public identifier, or null if not
  95      *                 available.
  96      * @param systemId The notation system identifier.
  97      * @see org.xml.sax.DTDHandler#notationDecl
  98      */
  99     public void notationDecl (String name, String publicId, String systemId)
 100     {
 101         // no op
 102     }
 103
 104
 105     /**
 106      * Receive notification of an unparsed entity declaration.
 107      *
 108      * <p>By default, do nothing.  Application writers may override this
 109      * method in a subclass to keep track of the unparsed entities
 110      * declared in a document.</p>
 111      *
 112      * @param name The entity name.
 113      * @param publicId The entity public identifier, or null if not
 114      *                 available.
 115      * @param systemId The entity system identifier.
 116      * @param notationName The name of the associated notation.
 117      * @see org.xml.sax.DTDHandler#unparsedEntityDecl
 118      */
 119     public void unparsedEntityDecl (String name, String publicId,
 120                                     String systemId, String notationName)
 121     {
 122         // no op
 123     }
 124
 125
 126
 127     ////////////////////////////////////////////////////////////////////
 128     // Default implementation of DocumentHandler interface.
 129     ////////////////////////////////////////////////////////////////////
 130
 131
 132     /**
 133      * Receive a Locator object for document events.
 134      *
 135      * <p>By default, do nothing.  Application writers may override this
 136      * method in a subclass if they wish to store the locator for use
 137      * with other document events.</p>
 138      *
 139      * @param locator A locator for all SAX document events.
 140      * @see org.xml.sax.DocumentHandler#setDocumentLocator
 141      * @see org.xml.sax.Locator
 142      */
 143     public void setDocumentLocator (Locator locator)
 144     {
 145         // no op
 146     }
 147
 148
 149     /**
 150      * Receive notification of the beginning of the document.
 151      *
 152      * <p>By default, do nothing.  Application writers may override this
 153      * method in a subclass to take specific actions at the beginning
 154      * of a document (such as allocating the root node of a tree or
 155      * creating an output file).</p>
 156      *
 157      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 158      *            wrapping another exception.
 159      * @see org.xml.sax.DocumentHandler#startDocument
 160      */
 161     public void startDocument ()
 162         throws SAXException
 163     {
 164         // no op
 165     }
 166
 167
 168     /**
 169      * Receive notification of the end of the document.
 170      *
 171      * <p>By default, do nothing.  Application writers may override this
 172      * method in a subclass to take specific actions at the beginning
 173      * of a document (such as finalising a tree or closing an output
 174      * file).</p>
 175      *
 176      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 177      *            wrapping another exception.
 178      * @see org.xml.sax.DocumentHandler#endDocument
 179      */
 180     public void endDocument ()
 181         throws SAXException
 182     {
 183         // no op
 184     }
 185
 186
 187     /**
 188      * Receive notification of the start of an element.
 189      *
 190      * <p>By default, do nothing.  Application writers may override this
 191      * method in a subclass to take specific actions at the start of
 192      * each element (such as allocating a new tree node or writing
 193      * output to a file).</p>
 194      *
 195      * @param name The element type name.
 196      * @param attributes The specified or defaulted attributes.
 197      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 198      *            wrapping another exception.
 199      * @see org.xml.sax.DocumentHandler#startElement
 200      */
 201     public void startElement (String name, AttributeList attributes)
 202         throws SAXException
 203     {
 204         // no op
 205     }
 206
 207
 208     /**
 209      * Receive notification of the end of an element.
 210      *
 211      * <p>By default, do nothing.  Application writers may override this
 212      * method in a subclass to take specific actions at the end of
 213      * each element (such as finalising a tree node or writing
 214      * output to a file).</p>
 215      *
 216      * @param name the element name
 217      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 218      *            wrapping another exception.
 219      * @see org.xml.sax.DocumentHandler#endElement
 220      */
 221     public void endElement (String name)
 222         throws SAXException
 223     {
 224         // no op
 225     }
 226
 227
 228     /**
 229      * Receive notification of character data inside an element.
 230      *
 231      * <p>By default, do nothing.  Application writers may override this
 232      * method to take specific actions for each chunk of character data
 233      * (such as adding the data to a node or buffer, or printing it to
 234      * a file).</p>
 235      *
 236      * @param ch The characters.
 237      * @param start The start position in the character array.
 238      * @param length The number of characters to use from the
 239      *               character array.
 240      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 241      *            wrapping another exception.
 242      * @see org.xml.sax.DocumentHandler#characters
 243      */
 244     public void characters (char ch[], int start, int length)
 245         throws SAXException
 246     {
 247         // no op
 248     }
 249
 250
 251     /**
 252      * Receive notification of ignorable whitespace in element content.
 253      *
 254      * <p>By default, do nothing.  Application writers may override this
 255      * method to take specific actions for each chunk of ignorable
 256      * whitespace (such as adding data to a node or buffer, or printing
 257      * it to a file).</p>
 258      *
 259      * @param ch The whitespace characters.
 260      * @param start The start position in the character array.
 261      * @param length The number of characters to use from the
 262      *               character array.
 263      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 264      *            wrapping another exception.
 265      * @see org.xml.sax.DocumentHandler#ignorableWhitespace
 266      */
 267     public void ignorableWhitespace (char ch[], int start, int length)
 268         throws SAXException
 269     {
 270         // no op
 271     }
 272
 273
 274     /**
 275      * Receive notification of a processing instruction.
 276      *
 277      * <p>By default, do nothing.  Application writers may override this
 278      * method in a subclass to take specific actions for each
 279      * processing instruction, such as setting status variables or
 280      * invoking other methods.</p>
 281      *
 282      * @param target The processing instruction target.
 283      * @param data The processing instruction data, or null if
 284      *             none is supplied.
 285      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 286      *            wrapping another exception.
 287      * @see org.xml.sax.DocumentHandler#processingInstruction
 288      */
 289     public void processingInstruction (String target, String data)
 290         throws SAXException
 291     {
 292         // no op
 293     }
 294
 295
 296
 297     ////////////////////////////////////////////////////////////////////
 298     // Default implementation of the ErrorHandler interface.
 299     ////////////////////////////////////////////////////////////////////
 300
 301
 302     /**
 303      * Receive notification of a parser warning.
 304      *
 305      * <p>The default implementation does nothing.  Application writers
 306      * may override this method in a subclass to take specific actions
 307      * for each warning, such as inserting the message in a log file or
 308      * printing it to the console.</p>
 309      *
 310      * @param e The warning information encoded as an exception.
 311      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 312      *            wrapping another exception.
 313      * @see org.xml.sax.ErrorHandler#warning
 314      * @see org.xml.sax.SAXParseException
 315      */
 316     public void warning (SAXParseException e)
 317         throws SAXException
 318     {
 319         // no op
 320     }
 321
 322
 323     /**
 324      * Receive notification of a recoverable parser error.
 325      *
 326      * <p>The default implementation does nothing.  Application writers
 327      * may override this method in a subclass to take specific actions
 328      * for each error, such as inserting the message in a log file or
 329      * printing it to the console.</p>
 330      *
 331      * @param e The warning information encoded as an exception.
 332      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 333      *            wrapping another exception.
 334      * @see org.xml.sax.ErrorHandler#warning
 335      * @see org.xml.sax.SAXParseException
 336      */
 337     public void error (SAXParseException e)
 338         throws SAXException
 339     {
 340         // no op
 341     }
 342
 343
 344     /**
 345      * Report a fatal XML parsing error.
 346      *
 347      * <p>The default implementation throws a SAXParseException.
 348      * Application writers may override this method in a subclass if
 349      * they need to take specific actions for each fatal error (such as
 350      * collecting all of the errors into a single report): in any case,
 351      * the application must stop all regular processing when this
 352      * method is invoked, since the document is no longer reliable, and
 353      * the parser may no longer report parsing events.</p>
 354      *
 355      * @param e The error information encoded as an exception.
 356      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 357      *            wrapping another exception.
 358      * @see org.xml.sax.ErrorHandler#fatalError
 359      * @see org.xml.sax.SAXParseException
 360      */
 361     public void fatalError (SAXParseException e)
 362         throws SAXException
 363     {
 364         throw e;
 365     }
 366
 367 }
 368
 369 // end of HandlerBase.java