Source for org.xml.sax.helpers.DefaultHandler

   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 2004/12/23 22:38:42 mark 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: 
  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: 
  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: 
 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: 
 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