libjava/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.3.2.3 2002/01/29 21:34:14 dbrownell 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 \f
  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 \f
  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 \f
 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 type name.
 217      * @param attributes The specified or defaulted attributes.
 218      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 219      *            wrapping another exception.
 220      * @see org.xml.sax.DocumentHandler#endElement
 221      */
 222     public void endElement (String name)
 223         throws SAXException
 224     {
 225         // no op
 226     }
 227
 228
 229     /**
 230      * Receive notification of character data inside an element.
 231      *
 232      * <p>By default, do nothing.  Application writers may override this
 233      * method to take specific actions for each chunk of character data
 234      * (such as adding the data to a node or buffer, or printing it to
 235      * a file).</p>
 236      *
 237      * @param ch The characters.
 238      * @param start The start position in the character array.
 239      * @param length The number of characters to use from the
 240      *               character array.
 241      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 242      *            wrapping another exception.
 243      * @see org.xml.sax.DocumentHandler#characters
 244      */
 245     public void characters (char ch[], int start, int length)
 246         throws SAXException
 247     {
 248         // no op
 249     }
 250
 251
 252     /**
 253      * Receive notification of ignorable whitespace in element content.
 254      *
 255      * <p>By default, do nothing.  Application writers may override this
 256      * method to take specific actions for each chunk of ignorable
 257      * whitespace (such as adding data to a node or buffer, or printing
 258      * it to a file).</p>
 259      *
 260      * @param ch The whitespace characters.
 261      * @param start The start position in the character array.
 262      * @param length The number of characters to use from the
 263      *               character array.
 264      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 265      *            wrapping another exception.
 266      * @see org.xml.sax.DocumentHandler#ignorableWhitespace
 267      */
 268     public void ignorableWhitespace (char ch[], int start, int length)
 269         throws SAXException
 270     {
 271         // no op
 272     }
 273
 274
 275     /**
 276      * Receive notification of a processing instruction.
 277      *
 278      * <p>By default, do nothing.  Application writers may override this
 279      * method in a subclass to take specific actions for each
 280      * processing instruction, such as setting status variables or
 281      * invoking other methods.</p>
 282      *
 283      * @param target The processing instruction target.
 284      * @param data The processing instruction data, or null if
 285      *             none is supplied.
 286      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 287      *            wrapping another exception.
 288      * @see org.xml.sax.DocumentHandler#processingInstruction
 289      */
 290     public void processingInstruction (String target, String data)
 291         throws SAXException
 292     {
 293         // no op
 294     }
 295
 296
 297 \f
 298     ////////////////////////////////////////////////////////////////////
 299     // Default implementation of the ErrorHandler interface.
 300     ////////////////////////////////////////////////////////////////////
 301
 302
 303     /**
 304      * Receive notification of a parser warning.
 305      *
 306      * <p>The default implementation does nothing.  Application writers
 307      * may override this method in a subclass to take specific actions
 308      * for each warning, such as inserting the message in a log file or
 309      * printing it to the console.</p>
 310      *
 311      * @param e The warning information encoded as an exception.
 312      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 313      *            wrapping another exception.
 314      * @see org.xml.sax.ErrorHandler#warning
 315      * @see org.xml.sax.SAXParseException
 316      */
 317     public void warning (SAXParseException e)
 318         throws SAXException
 319     {
 320         // no op
 321     }
 322
 323
 324     /**
 325      * Receive notification of a recoverable parser error.
 326      *
 327      * <p>The default implementation does nothing.  Application writers
 328      * may override this method in a subclass to take specific actions
 329      * for each error, such as inserting the message in a log file or
 330      * printing it to the console.</p>
 331      *
 332      * @param e The warning information encoded as an exception.
 333      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 334      *            wrapping another exception.
 335      * @see org.xml.sax.ErrorHandler#warning
 336      * @see org.xml.sax.SAXParseException
 337      */
 338     public void error (SAXParseException e)
 339         throws SAXException
 340     {
 341         // no op
 342     }
 343
 344
 345     /**
 346      * Report a fatal XML parsing error.
 347      *
 348      * <p>The default implementation throws a SAXParseException.
 349      * Application writers may override this method in a subclass if
 350      * they need to take specific actions for each fatal error (such as
 351      * collecting all of the errors into a single report): in any case,
 352      * the application must stop all regular processing when this
 353      * method is invoked, since the document is no longer reliable, and
 354      * the parser may no longer report parsing events.</p>
 355      *
 356      * @param e The error information encoded as an exception.
 357      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 358      *            wrapping another exception.
 359      * @see org.xml.sax.ErrorHandler#fatalError
 360      * @see org.xml.sax.SAXParseException
 361      */
 362     public void fatalError (SAXParseException e)
 363         throws SAXException
 364     {
 365         throw e;
 366     }
 367
 368 }
 369
 370 // end of HandlerBase.java