001// SAX default handler base class. 002// No warranty; no copyright -- use this as you will. 003// $Id: HandlerBase.java,v 1.1 2001/03/05 21:40:05 jstrachan Exp $ 004 005package org.xml.sax; 006 007/** 008 * Default base class for handlers. 009 * 010 * <blockquote> 011 * <em>This module, both source code and documentation, is in the 012 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 013 * </blockquote> 014 * 015 * <p>This class implements the default behaviour for four SAX1 016 * interfaces: EntityResolver, DTDHandler, DocumentHandler, 017 * and ErrorHandler. It is now obsolete, but is included in SAX2 to 018 * support legacy SAX1 applications. SAX2 applications should use 019 * the {@link org.xml.sax.helpers.DefaultHandler DefaultHandler} 020 * class instead.</p> 021 * 022 * <p>Application writers can extend this class when they need to 023 * implement only part of an interface; parser writers can 024 * instantiate this class to provide default handlers when the 025 * application has not supplied its own.</p> 026 * 027 * <p>Note that the use of this class is optional.</p> 028 * 029 * @deprecated This class works with the deprecated 030 * {@link org.xml.sax.DocumentHandler DocumentHandler} 031 * interface. It has been replaced by the SAX2 032 * {@link org.xml.sax.helpers.DefaultHandler DefaultHandler} 033 * class. 034 * @since SAX 1.0 035 * @author David Megginson, 036 * <a href="mailto:sax@megginson.com">sax@megginson.com</a> 037 * @version 2.0 038 * @see org.xml.sax.EntityResolver 039 * @see org.xml.sax.DTDHandler 040 * @see org.xml.sax.DocumentHandler 041 * @see org.xml.sax.ErrorHandler 042 */ 043public class HandlerBase 044 implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler 045{ 046 047 048 //////////////////////////////////////////////////////////////////// 049 // Default implementation of the EntityResolver interface. 050 //////////////////////////////////////////////////////////////////// 051 052 /** 053 * Resolve an external entity. 054 * 055 * <p>Always return null, so that the parser will use the system 056 * identifier provided in the XML document. This method implements 057 * the SAX default behaviour: application writers can override it 058 * in a subclass to do special translations such as catalog lookups 059 * or URI redirection.</p> 060 * 061 * @param publicId The public identifer, or null if none is 062 * available. 063 * @param systemId The system identifier provided in the XML 064 * document. 065 * @return The new input source, or null to require the 066 * default behaviour. 067 * @exception org.xml.sax.SAXException Any SAX exception, possibly 068 * wrapping another exception. 069 * @see org.xml.sax.EntityResolver#resolveEntity 070 */ 071 public InputSource resolveEntity (String publicId, String systemId) 072 throws SAXException 073 { 074 return null; 075 } 076 077 078 079 //////////////////////////////////////////////////////////////////// 080 // Default implementation of DTDHandler interface. 081 //////////////////////////////////////////////////////////////////// 082 083 084 /** 085 * Receive notification of a notation declaration. 086 * 087 * <p>By default, do nothing. Application writers may override this 088 * method in a subclass if they wish to keep track of the notations 089 * declared in a document.</p> 090 * 091 * @param name The notation name. 092 * @param publicId The notation public identifier, or null if not 093 * available. 094 * @param systemId The notation system identifier. 095 * @see org.xml.sax.DTDHandler#notationDecl 096 */ 097 public void notationDecl (String name, String publicId, String systemId) 098 { 099 // no op 100 } 101 102 103 /** 104 * Receive notification of an unparsed entity declaration. 105 * 106 * <p>By default, do nothing. Application writers may override this 107 * method in a subclass to keep track of the unparsed entities 108 * declared in a document.</p> 109 * 110 * @param name The entity name. 111 * @param publicId The entity public identifier, or null if not 112 * available. 113 * @param systemId The entity system identifier. 114 * @param notationName The name of the associated notation. 115 * @see org.xml.sax.DTDHandler#unparsedEntityDecl 116 */ 117 public void unparsedEntityDecl (String name, String publicId, 118 String systemId, String notationName) 119 { 120 // no op 121 } 122 123 124 125 //////////////////////////////////////////////////////////////////// 126 // Default implementation of DocumentHandler interface. 127 //////////////////////////////////////////////////////////////////// 128 129 130 /** 131 * Receive a Locator object for document events. 132 * 133 * <p>By default, do nothing. Application writers may override this 134 * method in a subclass if they wish to store the locator for use 135 * with other document events.</p> 136 * 137 * @param locator A locator for all SAX document events. 138 * @see org.xml.sax.DocumentHandler#setDocumentLocator 139 * @see org.xml.sax.Locator 140 */ 141 public void setDocumentLocator (Locator locator) 142 { 143 // no op 144 } 145 146 147 /** 148 * Receive notification of the beginning of the document. 149 * 150 * <p>By default, do nothing. Application writers may override this 151 * method in a subclass to take specific actions at the beginning 152 * of a document (such as allocating the root node of a tree or 153 * creating an output file).</p> 154 * 155 * @exception org.xml.sax.SAXException Any SAX exception, possibly 156 * wrapping another exception. 157 * @see org.xml.sax.DocumentHandler#startDocument 158 */ 159 public void startDocument () 160 throws SAXException 161 { 162 // no op 163 } 164 165 166 /** 167 * Receive notification of the end of the document. 168 * 169 * <p>By default, do nothing. Application writers may override this 170 * method in a subclass to take specific actions at the beginning 171 * of a document (such as finalising a tree or closing an output 172 * file).</p> 173 * 174 * @exception org.xml.sax.SAXException Any SAX exception, possibly 175 * wrapping another exception. 176 * @see org.xml.sax.DocumentHandler#endDocument 177 */ 178 public void endDocument () 179 throws SAXException 180 { 181 // no op 182 } 183 184 185 /** 186 * Receive notification of the start of an element. 187 * 188 * <p>By default, do nothing. Application writers may override this 189 * method in a subclass to take specific actions at the start of 190 * each element (such as allocating a new tree node or writing 191 * output to a file).</p> 192 * 193 * @param name The element type name. 194 * @param attributes The specified or defaulted attributes. 195 * @exception org.xml.sax.SAXException Any SAX exception, possibly 196 * wrapping another exception. 197 * @see org.xml.sax.DocumentHandler#startElement 198 */ 199 public void startElement (String name, AttributeList attributes) 200 throws SAXException 201 { 202 // no op 203 } 204 205 206 /** 207 * Receive notification of the end of an element. 208 * 209 * <p>By default, do nothing. Application writers may override this 210 * method in a subclass to take specific actions at the end of 211 * each element (such as finalising a tree node or writing 212 * output to a file).</p> 213 * 214 * @param name The element type name. 215 * @param attributes The specified or defaulted attributes. 216 * @exception org.xml.sax.SAXException Any SAX exception, possibly 217 * wrapping another exception. 218 * @see org.xml.sax.DocumentHandler#endElement 219 */ 220 public void endElement (String name) 221 throws SAXException 222 { 223 // no op 224 } 225 226 227 /** 228 * Receive notification of character data inside an element. 229 * 230 * <p>By default, do nothing. Application writers may override this 231 * method to take specific actions for each chunk of character data 232 * (such as adding the data to a node or buffer, or printing it to 233 * a file).</p> 234 * 235 * @param ch The characters. 236 * @param start The start position in the character array. 237 * @param length The number of characters to use from the 238 * character array. 239 * @exception org.xml.sax.SAXException Any SAX exception, possibly 240 * wrapping another exception. 241 * @see org.xml.sax.DocumentHandler#characters 242 */ 243 public void characters (char ch[], int start, int length) 244 throws SAXException 245 { 246 // no op 247 } 248 249 250 /** 251 * Receive notification of ignorable whitespace in element content. 252 * 253 * <p>By default, do nothing. Application writers may override this 254 * method to take specific actions for each chunk of ignorable 255 * whitespace (such as adding data to a node or buffer, or printing 256 * it to a file).</p> 257 * 258 * @param ch The whitespace characters. 259 * @param start The start position in the character array. 260 * @param length The number of characters to use from the 261 * character array. 262 * @exception org.xml.sax.SAXException Any SAX exception, possibly 263 * wrapping another exception. 264 * @see org.xml.sax.DocumentHandler#ignorableWhitespace 265 */ 266 public void ignorableWhitespace (char ch[], int start, int length) 267 throws SAXException 268 { 269 // no op 270 } 271 272 273 /** 274 * Receive notification of a processing instruction. 275 * 276 * <p>By default, do nothing. Application writers may override this 277 * method in a subclass to take specific actions for each 278 * processing instruction, such as setting status variables or 279 * invoking other methods.</p> 280 * 281 * @param target The processing instruction target. 282 * @param data The processing instruction data, or null if 283 * none is supplied. 284 * @exception org.xml.sax.SAXException Any SAX exception, possibly 285 * wrapping another exception. 286 * @see org.xml.sax.DocumentHandler#processingInstruction 287 */ 288 public void processingInstruction (String target, String data) 289 throws SAXException 290 { 291 // no op 292 } 293 294 295 296 //////////////////////////////////////////////////////////////////// 297 // Default implementation of the ErrorHandler interface. 298 //////////////////////////////////////////////////////////////////// 299 300 301 /** 302 * Receive notification of a parser warning. 303 * 304 * <p>The default implementation does nothing. Application writers 305 * may override this method in a subclass to take specific actions 306 * for each warning, such as inserting the message in a log file or 307 * printing it to the console.</p> 308 * 309 * @param e The warning information encoded as an exception. 310 * @exception org.xml.sax.SAXException Any SAX exception, possibly 311 * wrapping another exception. 312 * @see org.xml.sax.ErrorHandler#warning 313 * @see org.xml.sax.SAXParseException 314 */ 315 public void warning (SAXParseException e) 316 throws SAXException 317 { 318 // no op 319 } 320 321 322 /** 323 * Receive notification of a recoverable parser error. 324 * 325 * <p>The default implementation does nothing. Application writers 326 * may override this method in a subclass to take specific actions 327 * for each error, such as inserting the message in a log file or 328 * printing it to the console.</p> 329 * 330 * @param e The warning information encoded as an exception. 331 * @exception org.xml.sax.SAXException Any SAX exception, possibly 332 * wrapping another exception. 333 * @see org.xml.sax.ErrorHandler#warning 334 * @see org.xml.sax.SAXParseException 335 */ 336 public void error (SAXParseException e) 337 throws SAXException 338 { 339 // no op 340 } 341 342 343 /** 344 * Report a fatal XML parsing error. 345 * 346 * <p>The default implementation throws a SAXParseException. 347 * Application writers may override this method in a subclass if 348 * they need to take specific actions for each fatal error (such as 349 * collecting all of the errors into a single report): in any case, 350 * the application must stop all regular processing when this 351 * method is invoked, since the document is no longer reliable, and 352 * the parser may no longer report parsing events.</p> 353 * 354 * @param e The error information encoded as an exception. 355 * @exception org.xml.sax.SAXException Any SAX exception, possibly 356 * wrapping another exception. 357 * @see org.xml.sax.ErrorHandler#fatalError 358 * @see org.xml.sax.SAXParseException 359 */ 360 public void fatalError (SAXParseException e) 361 throws SAXException 362 { 363 throw e; 364 } 365 366} 367 368// end of HandlerBase.java