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 $
6
7package org.xml.sax.helpers;
8
9import java.io.IOException;
10import org.xml.sax.Attributes;
11import org.xml.sax.ContentHandler;
12import org.xml.sax.DTDHandler;
13import org.xml.sax.EntityResolver;
14import org.xml.sax.ErrorHandler;
15import org.xml.sax.InputSource;
16import org.xml.sax.Locator;
17import org.xml.sax.SAXException;
18import org.xml.sax.SAXParseException;
19
20
21/**
22 * Default base class for SAX2 event handlers.
23 *
24 * <blockquote>
25 * <em>This module, both source code and documentation, is in the
26 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
27 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
28 * for further information.
29 * </blockquote>
30 *
31 * <p>This class is available as a convenience base class for SAX2
32 * applications: it provides default implementations for all of the
33 * callbacks in the four core SAX2 handler classes:</p>
34 *
35 * <ul>
36 * <li>{@link org.xml.sax.EntityResolver EntityResolver}</li>
37 * <li>{@link org.xml.sax.DTDHandler DTDHandler}</li>
38 * <li>{@link org.xml.sax.ContentHandler ContentHandler}</li>
39 * <li>{@link org.xml.sax.ErrorHandler ErrorHandler}</li>
40 * </ul>
41 *
42 * <p>Application writers can extend this class when they need to
43 * implement only part of an interface; parser writers can
44 * instantiate this class to provide default handlers when the
45 * application has not supplied its own.</p>
46 *
47 * <p>This class replaces the deprecated SAX1
48 * {@link org.xml.sax.HandlerBase HandlerBase} class.</p>
49 *
50 * @since SAX 2.0
51 * @author David Megginson,
52 * @version 2.0.1 (sax2r2)
53 * @see org.xml.sax.EntityResolver
54 * @see org.xml.sax.DTDHandler
55 * @see org.xml.sax.ContentHandler
56 * @see org.xml.sax.ErrorHandler
57 */
58public class DefaultHandler
59    implements EntityResolver, DTDHandler, ContentHandler, ErrorHandler
60{
61
62
63    ////////////////////////////////////////////////////////////////////
64    // Default implementation of the EntityResolver interface.
65    ////////////////////////////////////////////////////////////////////
66
67    /**
68     * Resolve an external entity.
69     *
70     * <p>Always return null, so that the parser will use the system
71     * identifier provided in the XML document.  This method implements
72     * the SAX default behaviour: application writers can override it
73     * in a subclass to do special translations such as catalog lookups
74     * or URI redirection.</p>
75     *
76     * @param publicId The public identifer, or null if none is
77     *                 available.
78     * @param systemId The system identifier provided in the XML
79     *                 document.
80     * @return The new input source, or null to require the
81     *         default behaviour.
82     * @exception java.io.IOException If there is an error setting
83     *            up the new input source.
84     * @exception org.xml.sax.SAXException Any SAX exception, possibly
85     *            wrapping another exception.
86     * @see org.xml.sax.EntityResolver#resolveEntity
87     */
88    public InputSource resolveEntity (String publicId, String systemId)
89    throws IOException, SAXException
90    {
91    return null;
92    }
93
94
95
96    ////////////////////////////////////////////////////////////////////
97    // Default implementation of DTDHandler interface.
98    ////////////////////////////////////////////////////////////////////
99
100
101    /**
102     * Receive notification of a notation declaration.
103     *
104     * <p>By default, do nothing.  Application writers may override this
105     * method in a subclass if they wish to keep track of the notations
106     * declared in a document.</p>
107     *
108     * @param name The notation name.
109     * @param publicId The notation public identifier, or null if not
110     *                 available.
111     * @param systemId The notation system identifier.
112     * @exception org.xml.sax.SAXException Any SAX exception, possibly
113     *            wrapping another exception.
114     * @see org.xml.sax.DTDHandler#notationDecl
115     */
116    public void notationDecl (String name, String publicId, String systemId)
117    throws SAXException
118    {
119    // no op
120    }
121
122
123    /**
124     * Receive notification of an unparsed entity declaration.
125     *
126     * <p>By default, do nothing.  Application writers may override this
127     * method in a subclass to keep track of the unparsed entities
128     * declared in a document.</p>
129     *
130     * @param name The entity name.
131     * @param publicId The entity public identifier, or null if not
132     *                 available.
133     * @param systemId The entity system identifier.
134     * @param notationName The name of the associated notation.
135     * @exception org.xml.sax.SAXException Any SAX exception, possibly
136     *            wrapping another exception.
137     * @see org.xml.sax.DTDHandler#unparsedEntityDecl
138     */
139    public void unparsedEntityDecl (String name, String publicId,
140                    String systemId, String notationName)
141    throws SAXException
142    {
143    // no op
144    }
145
146
147
148    ////////////////////////////////////////////////////////////////////
149    // Default implementation of ContentHandler interface.
150    ////////////////////////////////////////////////////////////////////
151
152
153    /**
154     * Receive a Locator object for document events.
155     *
156     * <p>By default, do nothing.  Application writers may override this
157     * method in a subclass if they wish to store the locator for use
158     * with other document events.</p>
159     *
160     * @param locator A locator for all SAX document events.
161     * @see org.xml.sax.ContentHandler#setDocumentLocator
162     * @see org.xml.sax.Locator
163     */
164    public void setDocumentLocator (Locator locator)
165    {
166    // no op
167    }
168
169
170    /**
171     * Receive notification of the beginning of the document.
172     *
173     * <p>By default, do nothing.  Application writers may override this
174     * method in a subclass to take specific actions at the beginning
175     * of a document (such as allocating the root node of a tree or
176     * creating an output file).</p>
177     *
178     * @exception org.xml.sax.SAXException Any SAX exception, possibly
179     *            wrapping another exception.
180     * @see org.xml.sax.ContentHandler#startDocument
181     */
182    public void startDocument ()
183    throws SAXException
184    {
185    // no op
186    }
187
188
189    /**
190     * Receive notification of the end of the document.
191     *
192     * <p>By default, do nothing.  Application writers may override this
193     * method in a subclass to take specific actions at the end
194     * of a document (such as finalising a tree or closing an output
195     * file).</p>
196     *
197     * @exception org.xml.sax.SAXException Any SAX exception, possibly
198     *            wrapping another exception.
199     * @see org.xml.sax.ContentHandler#endDocument
200     */
201    public void endDocument ()
202    throws SAXException
203    {
204    // no op
205    }
206
207
208    /**
209     * Receive notification of the start of a Namespace mapping.
210     *
211     * <p>By default, do nothing.  Application writers may override this
212     * method in a subclass to take specific actions at the start of
213     * each Namespace prefix scope (such as storing the prefix mapping).</p>
214     *
215     * @param prefix The Namespace prefix being declared.
216     * @param uri The Namespace URI mapped to the prefix.
217     * @exception org.xml.sax.SAXException Any SAX exception, possibly
218     *            wrapping another exception.
219     * @see org.xml.sax.ContentHandler#startPrefixMapping
220     */
221    public void startPrefixMapping (String prefix, String uri)
222    throws SAXException
223    {
224    // no op
225    }
226
227
228    /**
229     * Receive notification of the end of a Namespace mapping.
230     *
231     * <p>By default, do nothing.  Application writers may override this
232     * method in a subclass to take specific actions at the end of
233     * each prefix mapping.</p>
234     *
235     * @param prefix The Namespace prefix being declared.
236     * @exception org.xml.sax.SAXException Any SAX exception, possibly
237     *            wrapping another exception.
238     * @see org.xml.sax.ContentHandler#endPrefixMapping
239     */
240    public void endPrefixMapping (String prefix)
241    throws SAXException
242    {
243    // no op
244    }
245
246
247    /**
248     * Receive notification of the start of an element.
249     *
250     * <p>By default, do nothing.  Application writers may override this
251     * method in a subclass to take specific actions at the start of
252     * each element (such as allocating a new tree node or writing
253     * output to a file).</p>
254     *
255     * @param uri The Namespace URI, or the empty string if the
256     *        element has no Namespace URI or if Namespace
257     *        processing is not being performed.
258     * @param localName The local name (without prefix), or the
259     *        empty string if Namespace processing is not being
260     *        performed.
261     * @param qName The qualified name (with prefix), or the
262     *        empty string if qualified names are not available.
263     * @param attributes The attributes attached to the element.  If
264     *        there are no attributes, it shall be an empty
265     *        Attributes object.
266     * @exception org.xml.sax.SAXException Any SAX exception, possibly
267     *            wrapping another exception.
268     * @see org.xml.sax.ContentHandler#startElement
269     */
270    public void startElement (String uri, String localName,
271                  String qName, Attributes attributes)
272    throws SAXException
273    {
274    // no op
275    }
276
277
278    /**
279     * Receive notification of the end of an element.
280     *
281     * <p>By default, do nothing.  Application writers may override this
282     * method in a subclass to take specific actions at the end of
283     * each element (such as finalising a tree node or writing
284     * output to a file).</p>
285     *
286     * @param uri The Namespace URI, or the empty string if the
287     *        element has no Namespace URI or if Namespace
288     *        processing is not being performed.
289     * @param localName The local name (without prefix), or the
290     *        empty string if Namespace processing is not being
291     *        performed.
292     * @param qName The qualified name (with prefix), or the
293     *        empty string if qualified names are not available.
294     * @exception org.xml.sax.SAXException Any SAX exception, possibly
295     *            wrapping another exception.
296     * @see org.xml.sax.ContentHandler#endElement
297     */
298    public void endElement (String uri, String localName, String qName)
299    throws SAXException
300    {
301    // no op
302    }
303
304
305    /**
306     * Receive notification of character data inside an element.
307     *
308     * <p>By default, do nothing.  Application writers may override this
309     * method to take specific actions for each chunk of character data
310     * (such as adding the data to a node or buffer, or printing it to
311     * a file).</p>
312     *
313     * @param ch The characters.
314     * @param start The start position in the character array.
315     * @param length The number of characters to use from the
316     *               character array.
317     * @exception org.xml.sax.SAXException Any SAX exception, possibly
318     *            wrapping another exception.
319     * @see org.xml.sax.ContentHandler#characters
320     */
321    public void characters (char ch[], int start, int length)
322    throws SAXException
323    {
324    // no op
325    }
326
327
328    /**
329     * Receive notification of ignorable whitespace in element content.
330     *
331     * <p>By default, do nothing.  Application writers may override this
332     * method to take specific actions for each chunk of ignorable
333     * whitespace (such as adding data to a node or buffer, or printing
334     * it to a file).</p>
335     *
336     * @param ch The whitespace characters.
337     * @param start The start position in the character array.
338     * @param length The number of characters to use from the
339     *               character array.
340     * @exception org.xml.sax.SAXException Any SAX exception, possibly
341     *            wrapping another exception.
342     * @see org.xml.sax.ContentHandler#ignorableWhitespace
343     */
344    public void ignorableWhitespace (char ch[], int start, int length)
345    throws SAXException
346    {
347    // no op
348    }
349
350
351    /**
352     * Receive notification of a processing instruction.
353     *
354     * <p>By default, do nothing.  Application writers may override this
355     * method in a subclass to take specific actions for each
356     * processing instruction, such as setting status variables or
357     * invoking other methods.</p>
358     *
359     * @param target The processing instruction target.
360     * @param data The processing instruction data, or null if
361     *             none is supplied.
362     * @exception org.xml.sax.SAXException Any SAX exception, possibly
363     *            wrapping another exception.
364     * @see org.xml.sax.ContentHandler#processingInstruction
365     */
366    public void processingInstruction (String target, String data)
367    throws SAXException
368    {
369    // no op
370    }
371
372
373    /**
374     * Receive notification of a skipped entity.
375     *
376     * <p>By default, do nothing.  Application writers may override this
377     * method in a subclass to take specific actions for each
378     * processing instruction, such as setting status variables or
379     * invoking other methods.</p>
380     *
381     * @param name The name of the skipped entity.
382     * @exception org.xml.sax.SAXException Any SAX exception, possibly
383     *            wrapping another exception.
384     * @see org.xml.sax.ContentHandler#processingInstruction
385     */
386    public void skippedEntity (String name)
387    throws SAXException
388    {
389    // no op
390    }
391
392
393
394    ////////////////////////////////////////////////////////////////////
395    // Default implementation of the ErrorHandler interface.
396    ////////////////////////////////////////////////////////////////////
397
398
399    /**
400     * Receive notification of a parser warning.
401     *
402     * <p>The default implementation does nothing.  Application writers
403     * may override this method in a subclass to take specific actions
404     * for each warning, such as inserting the message in a log file or
405     * printing it to the console.</p>
406     *
407     * @param e The warning information encoded as an exception.
408     * @exception org.xml.sax.SAXException Any SAX exception, possibly
409     *            wrapping another exception.
410     * @see org.xml.sax.ErrorHandler#warning
411     * @see org.xml.sax.SAXParseException
412     */
413    public void warning (SAXParseException e)
414    throws SAXException
415    {
416    // no op
417    }
418
419
420    /**
421     * Receive notification of a recoverable parser error.
422     *
423     * <p>The default implementation does nothing.  Application writers
424     * may override this method in a subclass to take specific actions
425     * for each error, such as inserting the message in a log file or
426     * printing it to the console.</p>
427     *
428     * @param e The warning information encoded as an exception.
429     * @exception org.xml.sax.SAXException Any SAX exception, possibly
430     *            wrapping another exception.
431     * @see org.xml.sax.ErrorHandler#warning
432     * @see org.xml.sax.SAXParseException
433     */
434    public void error (SAXParseException e)
435    throws SAXException
436    {
437    // no op
438    }
439
440
441    /**
442     * Report a fatal XML parsing error.
443     *
444     * <p>The default implementation throws a SAXParseException.
445     * Application writers may override this method in a subclass if
446     * they need to take specific actions for each fatal error (such as
447     * collecting all of the errors into a single report): in any case,
448     * the application must stop all regular processing when this
449     * method is invoked, since the document is no longer reliable, and
450     * the parser may no longer report parsing events.</p>
451     *
452     * @param e The error information encoded as an exception.
453     * @exception org.xml.sax.SAXException Any SAX exception, possibly
454     *            wrapping another exception.
455     * @see org.xml.sax.ErrorHandler#fatalError
456     * @see org.xml.sax.SAXParseException
457     */
458    public void fatalError (SAXParseException e)
459    throws SAXException
460    {
461    throw e;
462    }
463
464}
465
466// end of DefaultHandler.java
467