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.9 2004/04/26 17:34:35 dmegginson Exp $
7 package org.xml.sax.helpers;
9 import java.io.IOException;
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;
23 * Default base class for SAX2 event handlers.
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.
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>
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>
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>
48 * <p>This class replaces the deprecated SAX1
49 * {@link org.xml.sax.HandlerBase HandlerBase} class.</p>
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
59 public class DefaultHandler
60 implements EntityResolver, DTDHandler, ContentHandler, ErrorHandler
64 ////////////////////////////////////////////////////////////////////
65 // Default implementation of the EntityResolver interface.
66 ////////////////////////////////////////////////////////////////////
69 * Resolve an external entity.
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>
77 * @param publicId The public identifer, or null if none is
79 * @param systemId The system identifier provided in the XML
81 * @return The new input source, or null to require the
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
90 public InputSource resolveEntity (String publicId, String systemId)
91 throws IOException, SAXException
98 ////////////////////////////////////////////////////////////////////
99 // Default implementation of DTDHandler interface.
100 ////////////////////////////////////////////////////////////////////
104 * Receive notification of a notation declaration.
106 * <p>By default, do nothing. Application writers may override this
107 * method in a subclass if they wish to keep track of the notations
108 * declared in a document.</p>
110 * @param name The notation name.
111 * @param publicId The notation public identifier, or null if not
113 * @param systemId The notation system identifier.
114 * @exception org.xml.sax.SAXException Any SAX exception, possibly
115 * wrapping another exception.
116 * @see org.xml.sax.DTDHandler#notationDecl
119 public void notationDecl (String name, String publicId, String systemId)
127 * Receive notification of an unparsed entity declaration.
129 * <p>By default, do nothing. Application writers may override this
130 * method in a subclass to keep track of the unparsed entities
131 * declared in a document.</p>
133 * @param name The entity name.
134 * @param publicId The entity public identifier, or null if not
136 * @param systemId The entity system identifier.
137 * @param notationName The name of the associated notation.
138 * @exception org.xml.sax.SAXException Any SAX exception, possibly
139 * wrapping another exception.
140 * @see org.xml.sax.DTDHandler#unparsedEntityDecl
143 public void unparsedEntityDecl (String name, String publicId,
144 String systemId, String notationName)
152 ////////////////////////////////////////////////////////////////////
153 // Default implementation of ContentHandler interface.
154 ////////////////////////////////////////////////////////////////////
158 * Receive a Locator object for document events.
160 * <p>By default, do nothing. Application writers may override this
161 * method in a subclass if they wish to store the locator for use
162 * with other document events.</p>
164 * @param locator A locator for all SAX document events.
165 * @see org.xml.sax.ContentHandler#setDocumentLocator
166 * @see org.xml.sax.Locator
169 public void setDocumentLocator (Locator locator)
176 * Receive notification of the beginning of the document.
178 * <p>By default, do nothing. Application writers may override this
179 * method in a subclass to take specific actions at the beginning
180 * of a document (such as allocating the root node of a tree or
181 * creating an output file).</p>
183 * @exception org.xml.sax.SAXException Any SAX exception, possibly
184 * wrapping another exception.
185 * @see org.xml.sax.ContentHandler#startDocument
188 public void startDocument ()
196 * Receive notification of the end of the document.
198 * <p>By default, do nothing. Application writers may override this
199 * method in a subclass to take specific actions at the end
200 * of a document (such as finalising a tree or closing an output
203 * @exception org.xml.sax.SAXException Any SAX exception, possibly
204 * wrapping another exception.
205 * @see org.xml.sax.ContentHandler#endDocument
208 public void endDocument ()
216 * Receive notification of the start of a Namespace mapping.
218 * <p>By default, do nothing. Application writers may override this
219 * method in a subclass to take specific actions at the start of
220 * each Namespace prefix scope (such as storing the prefix mapping).</p>
222 * @param prefix The Namespace prefix being declared.
223 * @param uri The Namespace URI mapped to the prefix.
224 * @exception org.xml.sax.SAXException Any SAX exception, possibly
225 * wrapping another exception.
226 * @see org.xml.sax.ContentHandler#startPrefixMapping
229 public void startPrefixMapping (String prefix, String uri)
237 * Receive notification of the end of a Namespace mapping.
239 * <p>By default, do nothing. Application writers may override this
240 * method in a subclass to take specific actions at the end of
241 * each prefix mapping.</p>
243 * @param prefix The Namespace prefix being declared.
244 * @exception org.xml.sax.SAXException Any SAX exception, possibly
245 * wrapping another exception.
246 * @see org.xml.sax.ContentHandler#endPrefixMapping
249 public void endPrefixMapping (String prefix)
257 * Receive notification of the start of an element.
259 * <p>By default, do nothing. Application writers may override this
260 * method in a subclass to take specific actions at the start of
261 * each element (such as allocating a new tree node or writing
262 * output to a file).</p>
264 * @param uri The Namespace URI, or the empty string if the
265 * element has no Namespace URI or if Namespace
266 * processing is not being performed.
267 * @param localName The local name (without prefix), or the
268 * empty string if Namespace processing is not being
270 * @param qName The qualified name (with prefix), or the
271 * empty string if qualified names are not available.
272 * @param attributes The attributes attached to the element. If
273 * there are no attributes, it shall be an empty
275 * @exception org.xml.sax.SAXException Any SAX exception, possibly
276 * wrapping another exception.
277 * @see org.xml.sax.ContentHandler#startElement
280 public void startElement (String uri, String localName,
281 String qName, Attributes attributes)
289 * Receive notification of the end of an element.
291 * <p>By default, do nothing. Application writers may override this
292 * method in a subclass to take specific actions at the end of
293 * each element (such as finalising a tree node or writing
294 * output to a file).</p>
296 * @param uri The Namespace URI, or the empty string if the
297 * element has no Namespace URI or if Namespace
298 * processing is not being performed.
299 * @param localName The local name (without prefix), or the
300 * empty string if Namespace processing is not being
302 * @param qName The qualified name (with prefix), or the
303 * empty string if qualified names are not available.
304 * @exception org.xml.sax.SAXException Any SAX exception, possibly
305 * wrapping another exception.
306 * @see org.xml.sax.ContentHandler#endElement
309 public void endElement (String uri, String localName, String qName)
317 * Receive notification of character data inside an element.
319 * <p>By default, do nothing. Application writers may override this
320 * method to take specific actions for each chunk of character data
321 * (such as adding the data to a node or buffer, or printing it to
324 * @param ch The characters.
325 * @param start The start position in the character array.
326 * @param length The number of characters to use from the
328 * @exception org.xml.sax.SAXException Any SAX exception, possibly
329 * wrapping another exception.
330 * @see org.xml.sax.ContentHandler#characters
333 public void characters (char ch[], int start, int length)
341 * Receive notification of ignorable whitespace in element content.
343 * <p>By default, do nothing. Application writers may override this
344 * method to take specific actions for each chunk of ignorable
345 * whitespace (such as adding data to a node or buffer, or printing
348 * @param ch The whitespace characters.
349 * @param start The start position in the character array.
350 * @param length The number of characters to use from the
352 * @exception org.xml.sax.SAXException Any SAX exception, possibly
353 * wrapping another exception.
354 * @see org.xml.sax.ContentHandler#ignorableWhitespace
357 public void ignorableWhitespace (char ch[], int start, int length)
365 * Receive notification of a processing instruction.
367 * <p>By default, do nothing. Application writers may override this
368 * method in a subclass to take specific actions for each
369 * processing instruction, such as setting status variables or
370 * invoking other methods.</p>
372 * @param target The processing instruction target.
373 * @param data The processing instruction data, or null if
375 * @exception org.xml.sax.SAXException Any SAX exception, possibly
376 * wrapping another exception.
377 * @see org.xml.sax.ContentHandler#processingInstruction
380 public void processingInstruction (String target, String data)
388 * Receive notification of a skipped entity.
390 * <p>By default, do nothing. Application writers may override this
391 * method in a subclass to take specific actions for each
392 * processing instruction, such as setting status variables or
393 * invoking other methods.</p>
395 * @param name The name of the skipped entity.
396 * @exception org.xml.sax.SAXException Any SAX exception, possibly
397 * wrapping another exception.
398 * @see org.xml.sax.ContentHandler#processingInstruction
401 public void skippedEntity (String name)
409 ////////////////////////////////////////////////////////////////////
410 // Default implementation of the ErrorHandler interface.
411 ////////////////////////////////////////////////////////////////////
415 * Receive notification of a parser warning.
417 * <p>The default implementation does nothing. Application writers
418 * may override this method in a subclass to take specific actions
419 * for each warning, such as inserting the message in a log file or
420 * printing it to the console.</p>
422 * @param e The warning information encoded as an exception.
423 * @exception org.xml.sax.SAXException Any SAX exception, possibly
424 * wrapping another exception.
425 * @see org.xml.sax.ErrorHandler#warning
426 * @see org.xml.sax.SAXParseException
429 public void warning (SAXParseException e)
437 * Receive notification of a recoverable parser error.
439 * <p>The default implementation does nothing. Application writers
440 * may override this method in a subclass to take specific actions
441 * for each error, such as inserting the message in a log file or
442 * printing it to the console.</p>
444 * @param e The warning information encoded as an exception.
445 * @exception org.xml.sax.SAXException Any SAX exception, possibly
446 * wrapping another exception.
447 * @see org.xml.sax.ErrorHandler#warning
448 * @see org.xml.sax.SAXParseException
451 public void error (SAXParseException e)
459 * Report a fatal XML parsing error.
461 * <p>The default implementation throws a SAXParseException.
462 * Application writers may override this method in a subclass if
463 * they need to take specific actions for each fatal error (such as
464 * collecting all of the errors into a single report): in any case,
465 * the application must stop all regular processing when this
466 * method is invoked, since the document is no longer reliable, and
467 * the parser may no longer report parsing events.</p>
469 * @param e The error information encoded as an exception.
470 * @exception org.xml.sax.SAXException Any SAX exception, possibly
471 * wrapping another exception.
472 * @see org.xml.sax.ErrorHandler#fatalError
473 * @see org.xml.sax.SAXParseException
476 public void fatalError (SAXParseException e)
484 // end of DefaultHandler.java