Source for org.xml.sax.HandlerBase

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