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.7 2004/04/26 17:34:34 dmegginson 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 @Deprecated 46 public class HandlerBase 47 implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler 48 { 49 50 51 //////////////////////////////////////////////////////////////////// 53 // Default implementation of the EntityResolver interface. 54 //////////////////////////////////////////////////////////////////// 55 56 /** 57 * Resolve an external entity. 58 * 59 * <p>Always return null, so that the parser will use the system 60 * identifier provided in the XML document. This method implements 61 * the SAX default behaviour: application writers can override it 62 * in a subclass to do special translations such as catalog lookups 63 * or URI redirection.</p> 64 * 65 * @param publicId The public identifer, or null if none is 66 * available. 67 * @param systemId The system identifier provided in the XML 68 * document. 69 * @return The new input source, or null to require the 70 * default behaviour. 71 * @exception org.xml.sax.SAXException Any SAX exception, possibly 72 * wrapping another exception. 73 * @see org.xml.sax.EntityResolver#resolveEntity 74 */ 75 public InputSource resolveEntity (String publicId, String systemId) 76 throws SAXException 77 { 78 return null; 79 } 80 81 82 83 //////////////////////////////////////////////////////////////////// 85 // Default implementation of DTDHandler interface. 86 //////////////////////////////////////////////////////////////////// 87 88 89 /** 90 * Receive notification of a notation declaration. 91 * 92 * <p>By default, do nothing. Application writers may override this 93 * method in a subclass if they wish to keep track of the notations 94 * declared in a document.</p> 95 * 96 * @param name The notation name. 97 * @param publicId The notation public identifier, or null if not 98 * available. 99 * @param systemId The notation system identifier. 100 * @see org.xml.sax.DTDHandler#notationDecl 101 */ 102 public void notationDecl (String name, String publicId, String systemId) 103 { 104 // no op 105 } 106 107 108 /** 109 * Receive notification of an unparsed entity declaration. 110 * 111 * <p>By default, do nothing. Application writers may override this 112 * method in a subclass to keep track of the unparsed entities 113 * declared in a document.</p> 114 * 115 * @param name The entity name. 116 * @param publicId The entity public identifier, or null if not 117 * available. 118 * @param systemId The entity system identifier. 119 * @param notationName The name of the associated notation. 120 * @see org.xml.sax.DTDHandler#unparsedEntityDecl 121 */ 122 public void unparsedEntityDecl (String name, String publicId, 123 String systemId, String notationName) 124 { 125 // no op 126 } 127 128 129 130 //////////////////////////////////////////////////////////////////// 132 // Default implementation of DocumentHandler interface. 133 //////////////////////////////////////////////////////////////////// 134 135 136 /** 137 * Receive a Locator object for document events. 138 * 139 * <p>By default, do nothing. Application writers may override this 140 * method in a subclass if they wish to store the locator for use 141 * with other document events.</p> 142 * 143 * @param locator A locator for all SAX document events. 144 * @see org.xml.sax.DocumentHandler#setDocumentLocator 145 * @see org.xml.sax.Locator 146 */ 147 public void setDocumentLocator (Locator locator) 148 { 149 // no op 150 } 151 152 153 /** 154 * Receive notification of the beginning of the document. 155 * 156 * <p>By default, do nothing. Application writers may override this 157 * method in a subclass to take specific actions at the beginning 158 * of a document (such as allocating the root node of a tree or 159 * creating an output file).</p> 160 * 161 * @exception org.xml.sax.SAXException Any SAX exception, possibly 162 * wrapping another exception. 163 * @see org.xml.sax.DocumentHandler#startDocument 164 */ 165 public void startDocument () 166 throws SAXException 167 { 168 // no op 169 } 170 171 172 /** 173 * Receive notification of the end of the document. 174 * 175 * <p>By default, do nothing. Application writers may override this 176 * method in a subclass to take specific actions at the beginning 177 * of a document (such as finalising a tree or closing an output 178 * file).</p> 179 * 180 * @exception org.xml.sax.SAXException Any SAX exception, possibly 181 * wrapping another exception. 182 * @see org.xml.sax.DocumentHandler#endDocument 183 */ 184 public void endDocument () 185 throws SAXException 186 { 187 // no op 188 } 189 190 191 /** 192 * Receive notification of the start of an element. 193 * 194 * <p>By default, do nothing. Application writers may override this 195 * method in a subclass to take specific actions at the start of 196 * each element (such as allocating a new tree node or writing 197 * output to a file).</p> 198 * 199 * @param name The element type name. 200 * @param attributes The specified or defaulted attributes. 201 * @exception org.xml.sax.SAXException Any SAX exception, possibly 202 * wrapping another exception. 203 * @see org.xml.sax.DocumentHandler#startElement 204 */ 205 public void startElement (String name, AttributeList attributes) 206 throws SAXException 207 { 208 // no op 209 } 210 211 212 /** 213 * Receive notification of the end of an element. 214 * 215 * <p>By default, do nothing. Application writers may override this 216 * method in a subclass to take specific actions at the end of 217 * each element (such as finalising a tree node or writing 218 * output to a file).</p> 219 * 220 * @param name the element name 221 * @exception org.xml.sax.SAXException Any SAX exception, possibly 222 * wrapping another exception. 223 * @see org.xml.sax.DocumentHandler#endElement 224 */ 225 public void endElement (String name) 226 throws SAXException 227 { 228 // no op 229 } 230 231 232 /** 233 * Receive notification of character data inside an element. 234 * 235 * <p>By default, do nothing. Application writers may override this 236 * method to take specific actions for each chunk of character data 237 * (such as adding the data to a node or buffer, or printing it to 238 * a file).</p> 239 * 240 * @param ch The characters. 241 * @param start The start position in the character array. 242 * @param length The number of characters to use from the 243 * character array. 244 * @exception org.xml.sax.SAXException Any SAX exception, possibly 245 * wrapping another exception. 246 * @see org.xml.sax.DocumentHandler#characters 247 */ 248 public void characters (char ch[], int start, int length) 249 throws SAXException 250 { 251 // no op 252 } 253 254 255 /** 256 * Receive notification of ignorable whitespace in element content. 257 * 258 * <p>By default, do nothing. Application writers may override this 259 * method to take specific actions for each chunk of ignorable 260 * whitespace (such as adding data to a node or buffer, or printing 261 * it to a file).</p> 262 * 263 * @param ch The whitespace characters. 264 * @param start The start position in the character array. 265 * @param length The number of characters to use from the 266 * character array. 267 * @exception org.xml.sax.SAXException Any SAX exception, possibly 268 * wrapping another exception. 269 * @see org.xml.sax.DocumentHandler#ignorableWhitespace 270 */ 271 public void ignorableWhitespace (char ch[], int start, int length) 272 throws SAXException 273 { 274 // no op 275 } 276 277 278 /** 279 * Receive notification of a processing instruction. 280 * 281 * <p>By default, do nothing. Application writers may override this 282 * method in a subclass to take specific actions for each 283 * processing instruction, such as setting status variables or 284 * invoking other methods.</p> 285 * 286 * @param target The processing instruction target. 287 * @param data The processing instruction data, or null if 288 * none is supplied. 289 * @exception org.xml.sax.SAXException Any SAX exception, possibly 290 * wrapping another exception. 291 * @see org.xml.sax.DocumentHandler#processingInstruction 292 */ 293 public void processingInstruction (String target, String data) 294 throws SAXException 295 { 296 // no op 297 } 298 299 300 301 //////////////////////////////////////////////////////////////////// 303 // Default implementation of the ErrorHandler interface. 304 //////////////////////////////////////////////////////////////////// 305 306 307 /** 308 * Receive notification of a parser warning. 309 * 310 * <p>The default implementation does nothing. Application writers 311 * may override this method in a subclass to take specific actions 312 * for each warning, such as inserting the message in a log file or 313 * printing it to the console.</p> 314 * 315 * @param e The warning information encoded as an exception. 316 * @exception org.xml.sax.SAXException Any SAX exception, possibly 317 * wrapping another exception. 318 * @see org.xml.sax.ErrorHandler#warning 319 * @see org.xml.sax.SAXParseException 320 */ 321 public void warning (SAXParseException e) 322 throws SAXException 323 { 324 // no op 325 } 326 327 328 /** 329 * Receive notification of a recoverable parser error. 330 * 331 * <p>The default implementation does nothing. Application writers 332 * may override this method in a subclass to take specific actions 333 * for each error, such as inserting the message in a log file or 334 * printing it to the console.</p> 335 * 336 * @param e The warning information encoded as an exception. 337 * @exception org.xml.sax.SAXException Any SAX exception, possibly 338 * wrapping another exception. 339 * @see org.xml.sax.ErrorHandler#warning 340 * @see org.xml.sax.SAXParseException 341 */ 342 public void error (SAXParseException e) 343 throws SAXException 344 { 345 // no op 346 } 347 348 349 /** 350 * Report a fatal XML parsing error. 351 * 352 * <p>The default implementation throws a SAXParseException. 353 * Application writers may override this method in a subclass if 354 * they need to take specific actions for each fatal error (such as 355 * collecting all of the errors into a single report): in any case, 356 * the application must stop all regular processing when this 357 * method is invoked, since the document is no longer reliable, and 358 * the parser may no longer report parsing events.</p> 359 * 360 * @param e The error information encoded as an exception. 361 * @exception org.xml.sax.SAXException Any SAX exception, possibly 362 * wrapping another exception. 363 * @see org.xml.sax.ErrorHandler#fatalError 364 * @see org.xml.sax.SAXParseException 365 */ 366 public void fatalError (SAXParseException e) 367 throws SAXException 368 { 369 throw e; 370 } 371 372 } 373 374 // end of HandlerBase.java 375