001 // SAX default handler base class. 002 // http://www.saxproject.org 003 // No warranty; no copyright -- use this as you will. 004 // $Id: HandlerBase.java,v 1.1 2004/12/23 22:38:42 mark Exp $ 005 006 package org.xml.sax; 007 008 /** 009 * Default base class for handlers. 010 * 011 * <blockquote> 012 * <em>This module, both source code and documentation, is in the 013 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 014 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> 015 * for further information. 016 * </blockquote> 017 * 018 * <p>This class implements the default behaviour for four SAX1 019 * interfaces: EntityResolver, DTDHandler, DocumentHandler, 020 * and ErrorHandler. It is now obsolete, but is included in SAX2 to 021 * support legacy SAX1 applications. SAX2 applications should use 022 * the {@link org.xml.sax.helpers.DefaultHandler DefaultHandler} 023 * class instead.</p> 024 * 025 * <p>Application writers can extend this class when they need to 026 * implement only part of an interface; parser writers can 027 * instantiate this class to provide default handlers when the 028 * application has not supplied its own.</p> 029 * 030 * <p>Note that the use of this class is optional.</p> 031 * 032 * @deprecated This class works with the deprecated 033 * {@link org.xml.sax.DocumentHandler DocumentHandler} 034 * interface. It has been replaced by the SAX2 035 * {@link org.xml.sax.helpers.DefaultHandler DefaultHandler} 036 * class. 037 * @since SAX 1.0 038 * @author David Megginson 039 * @version 2.0.1 (sax2r2) 040 * @see org.xml.sax.EntityResolver 041 * @see org.xml.sax.DTDHandler 042 * @see org.xml.sax.DocumentHandler 043 * @see org.xml.sax.ErrorHandler 044 */ 045 public class HandlerBase 046 implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler 047 { 048 049 050 //////////////////////////////////////////////////////////////////// 051 // Default implementation of the EntityResolver interface. 052 //////////////////////////////////////////////////////////////////// 053 054 /** 055 * Resolve an external entity. 056 * 057 * <p>Always return null, so that the parser will use the system 058 * identifier provided in the XML document. This method implements 059 * the SAX default behaviour: application writers can override it 060 * in a subclass to do special translations such as catalog lookups 061 * or URI redirection.</p> 062 * 063 * @param publicId The public identifer, or null if none is 064 * available. 065 * @param systemId The system identifier provided in the XML 066 * document. 067 * @return The new input source, or null to require the 068 * default behaviour. 069 * @exception org.xml.sax.SAXException Any SAX exception, possibly 070 * wrapping another exception. 071 * @see org.xml.sax.EntityResolver#resolveEntity 072 */ 073 public InputSource resolveEntity (String publicId, String systemId) 074 throws SAXException 075 { 076 return null; 077 } 078 079 080 081 //////////////////////////////////////////////////////////////////// 082 // Default implementation of DTDHandler interface. 083 //////////////////////////////////////////////////////////////////// 084 085 086 /** 087 * Receive notification of a notation declaration. 088 * 089 * <p>By default, do nothing. Application writers may override this 090 * method in a subclass if they wish to keep track of the notations 091 * declared in a document.</p> 092 * 093 * @param name The notation name. 094 * @param publicId The notation public identifier, or null if not 095 * available. 096 * @param systemId The notation system identifier. 097 * @see org.xml.sax.DTDHandler#notationDecl 098 */ 099 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