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 $
9 * Default base class for handlers.
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.
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}
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>
30 * <p>Note that the use of this class is optional.</p>
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}
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
45 public class HandlerBase
46 implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler
50 ////////////////////////////////////////////////////////////////////
51 // Default implementation of the EntityResolver interface.
52 ////////////////////////////////////////////////////////////////////
55 * Resolve an external entity.
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>
63 * @param publicId The public identifer, or null if none is
65 * @param systemId The system identifier provided in the XML
67 * @return The new input source, or null to require the
69 * @exception org.xml.sax.SAXException Any SAX exception, possibly
70 * wrapping another exception.
71 * @see org.xml.sax.EntityResolver#resolveEntity
74 public InputSource resolveEntity (String publicId, String systemId)
82 ////////////////////////////////////////////////////////////////////
83 // Default implementation of DTDHandler interface.
84 ////////////////////////////////////////////////////////////////////
88 * Receive notification of a notation declaration.
90 * <p>By default, do nothing. Application writers may override this
91 * method in a subclass if they wish to keep track of the notations
92 * declared in a document.</p>
94 * @param name The notation name.
95 * @param publicId The notation public identifier, or null if not
97 * @param systemId The notation system identifier.
98 * @see org.xml.sax.DTDHandler#notationDecl
101 public void notationDecl (String name, String publicId, String systemId)
108 * Receive notification of an unparsed entity declaration.
110 * <p>By default, do nothing. Application writers may override this
111 * method in a subclass to keep track of the unparsed entities
112 * declared in a document.</p>
114 * @param name The entity name.
115 * @param publicId The entity public identifier, or null if not
117 * @param systemId The entity system identifier.
118 * @param notationName The name of the associated notation.
119 * @see org.xml.sax.DTDHandler#unparsedEntityDecl
122 public void unparsedEntityDecl (String name, String publicId,
123 String systemId, String notationName)
130 ////////////////////////////////////////////////////////////////////
131 // Default implementation of DocumentHandler interface.
132 ////////////////////////////////////////////////////////////////////
136 * Receive a Locator object for document events.
138 * <p>By default, do nothing. Application writers may override this
139 * method in a subclass if they wish to store the locator for use
140 * with other document events.</p>
142 * @param locator A locator for all SAX document events.
143 * @see org.xml.sax.DocumentHandler#setDocumentLocator
144 * @see org.xml.sax.Locator
147 public void setDocumentLocator (Locator locator)
154 * Receive notification of the beginning of the document.
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>
161 * @exception org.xml.sax.SAXException Any SAX exception, possibly
162 * wrapping another exception.
163 * @see org.xml.sax.DocumentHandler#startDocument
166 public void startDocument ()
174 * Receive notification of the end of the document.
176 * <p>By default, do nothing. Application writers may override this
177 * method in a subclass to take specific actions at the beginning
178 * of a document (such as finalising a tree or closing an output
181 * @exception org.xml.sax.SAXException Any SAX exception, possibly
182 * wrapping another exception.
183 * @see org.xml.sax.DocumentHandler#endDocument
186 public void endDocument ()
194 * Receive notification of the start of an element.
196 * <p>By default, do nothing. Application writers may override this
197 * method in a subclass to take specific actions at the start of
198 * each element (such as allocating a new tree node or writing
199 * output to a file).</p>
201 * @param name The element type name.
202 * @param attributes The specified or defaulted attributes.
203 * @exception org.xml.sax.SAXException Any SAX exception, possibly
204 * wrapping another exception.
205 * @see org.xml.sax.DocumentHandler#startElement
208 public void startElement (String name, AttributeList attributes)
216 * Receive notification of the end of an element.
218 * <p>By default, do nothing. Application writers may override this
219 * method in a subclass to take specific actions at the end of
220 * each element (such as finalising a tree node or writing
221 * output to a file).</p>
223 * @param name the element name
224 * @exception org.xml.sax.SAXException Any SAX exception, possibly
225 * wrapping another exception.
226 * @see org.xml.sax.DocumentHandler#endElement
229 public void endElement (String name)
237 * Receive notification of character data inside an element.
239 * <p>By default, do nothing. Application writers may override this
240 * method to take specific actions for each chunk of character data
241 * (such as adding the data to a node or buffer, or printing it to
244 * @param ch The characters.
245 * @param start The start position in the character array.
246 * @param length The number of characters to use from the
248 * @exception org.xml.sax.SAXException Any SAX exception, possibly
249 * wrapping another exception.
250 * @see org.xml.sax.DocumentHandler#characters
253 public void characters (char ch[], int start, int length)
261 * Receive notification of ignorable whitespace in element content.
263 * <p>By default, do nothing. Application writers may override this
264 * method to take specific actions for each chunk of ignorable
265 * whitespace (such as adding data to a node or buffer, or printing
268 * @param ch The whitespace characters.
269 * @param start The start position in the character array.
270 * @param length The number of characters to use from the
272 * @exception org.xml.sax.SAXException Any SAX exception, possibly
273 * wrapping another exception.
274 * @see org.xml.sax.DocumentHandler#ignorableWhitespace
277 public void ignorableWhitespace (char ch[], int start, int length)
285 * Receive notification of a processing instruction.
287 * <p>By default, do nothing. Application writers may override this
288 * method in a subclass to take specific actions for each
289 * processing instruction, such as setting status variables or
290 * invoking other methods.</p>
292 * @param target The processing instruction target.
293 * @param data The processing instruction data, or null if
295 * @exception org.xml.sax.SAXException Any SAX exception, possibly
296 * wrapping another exception.
297 * @see org.xml.sax.DocumentHandler#processingInstruction
300 public void processingInstruction (String target, String data)
308 ////////////////////////////////////////////////////////////////////
309 // Default implementation of the ErrorHandler interface.
310 ////////////////////////////////////////////////////////////////////
314 * Receive notification of a parser warning.
316 * <p>The default implementation does nothing. Application writers
317 * may override this method in a subclass to take specific actions
318 * for each warning, such as inserting the message in a log file or
319 * printing it to the console.</p>
321 * @param e The warning information encoded as an exception.
322 * @exception org.xml.sax.SAXException Any SAX exception, possibly
323 * wrapping another exception.
324 * @see org.xml.sax.ErrorHandler#warning
325 * @see org.xml.sax.SAXParseException
328 public void warning (SAXParseException e)
336 * Receive notification of a recoverable parser error.
338 * <p>The default implementation does nothing. Application writers
339 * may override this method in a subclass to take specific actions
340 * for each error, such as inserting the message in a log file or
341 * printing it to the console.</p>
343 * @param e The warning information encoded as an exception.
344 * @exception org.xml.sax.SAXException Any SAX exception, possibly
345 * wrapping another exception.
346 * @see org.xml.sax.ErrorHandler#warning
347 * @see org.xml.sax.SAXParseException
350 public void error (SAXParseException e)
358 * Report a fatal XML parsing error.
360 * <p>The default implementation throws a SAXParseException.
361 * Application writers may override this method in a subclass if
362 * they need to take specific actions for each fatal error (such as
363 * collecting all of the errors into a single report): in any case,
364 * the application must stop all regular processing when this
365 * method is invoked, since the document is no longer reliable, and
366 * the parser may no longer report parsing events.</p>
368 * @param e The error information encoded as an exception.
369 * @exception org.xml.sax.SAXException Any SAX exception, possibly
370 * wrapping another exception.
371 * @see org.xml.sax.ErrorHandler#fatalError
372 * @see org.xml.sax.SAXParseException
375 public void fatalError (SAXParseException e)
383 // end of HandlerBase.java