001// DefaultHandler.java - default implementation of the core handlers.
002// Written by David Megginson, sax@megginson.com
003// NO WARRANTY!  This class is in the public domain.
004
005// $Id: DefaultHandler.java,v 1.1 2001/03/05 21:40:06 jstrachan Exp $
006
007package org.xml.sax.helpers;
008
009import org.xml.sax.InputSource;
010import org.xml.sax.Locator;
011import org.xml.sax.Attributes;
012import org.xml.sax.EntityResolver;
013import org.xml.sax.DTDHandler;
014import org.xml.sax.ContentHandler;
015import org.xml.sax.ErrorHandler;
016import org.xml.sax.SAXException;
017import org.xml.sax.SAXParseException;
018
019
020/**
021 * Default base class for SAX2 event handlers.
022 *
023 * <blockquote>
024 * <em>This module, both source code and documentation, is in the
025 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
026 * </blockquote>
027 *
028 * <p>This class is available as a convenience base class for SAX2
029 * applications: it provides default implementations for all of the
030 * callbacks in the four core SAX2 handler classes:</p>
031 *
032 * <ul>
033 * <li>{@link org.xml.sax.EntityResolver EntityResolver}</li>
034 * <li>{@link org.xml.sax.DTDHandler DTDHandler}</li>
035 * <li>{@link org.xml.sax.ContentHandler ContentHandler}</li>
036 * <li>{@link org.xml.sax.ErrorHandler ErrorHandler}</li>
037 * </ul>
038 *
039 * <p>Application writers can extend this class when they need to
040 * implement only part of an interface; parser writers can
041 * instantiate this class to provide default handlers when the
042 * application has not supplied its own.</p>
043 *
044 * <p>This class replaces the deprecated SAX1
045 * {@link org.xml.sax.HandlerBase HandlerBase} class.</p>
046 *
047 * @since SAX 2.0
048 * @author David Megginson, 
049 *         <a href="mailto:sax@megginson.com">sax@megginson.com</a>
050 * @version 2.0
051 * @see org.xml.sax.EntityResolver
052 * @see org.xml.sax.DTDHandler
053 * @see org.xml.sax.ContentHandler
054 * @see org.xml.sax.ErrorHandler
055 */
056public class DefaultHandler
057    implements EntityResolver, DTDHandler, ContentHandler, ErrorHandler
058{
059    
060
061    ////////////////////////////////////////////////////////////////////
062    // Default implementation of the EntityResolver interface.
063    ////////////////////////////////////////////////////////////////////
064    
065    /**
066     * Resolve an external entity.
067     *
068     * <p>Always return null, so that the parser will use the system
069     * identifier provided in the XML document.  This method implements
070     * the SAX default behaviour: application writers can override it
071     * in a subclass to do special translations such as catalog lookups
072     * or URI redirection.</p>
073     *
074     * @param publicId The public identifer, or null if none is
075     *                 available.
076     * @param systemId The system identifier provided in the XML 
077     *                 document.
078     * @return The new input source, or null to require the
079     *         default behaviour.
080     * @exception org.xml.sax.SAXException Any SAX exception, possibly
081     *            wrapping another exception.
082     * @see org.xml.sax.EntityResolver#resolveEntity
083     */
084    public InputSource resolveEntity (String publicId, String systemId)
085        throws SAXException
086    {
087        return null;
088    }
089    
090    
091
092    ////////////////////////////////////////////////////////////////////
093    // Default implementation of DTDHandler interface.
094    ////////////////////////////////////////////////////////////////////
095    
096    
097    /**
098     * Receive notification of a notation declaration.
099     *
100     * <p>By default, do nothing.  Application writers may override this
101     * method in a subclass if they wish to keep track of the notations
102     * declared in a document.</p>
103     *
104     * @param name The notation name.
105     * @param publicId The notation public identifier, or null if not
106     *                 available.
107     * @param systemId The notation system identifier.
108     * @exception org.xml.sax.SAXException Any SAX exception, possibly
109     *            wrapping another exception.
110     * @see org.xml.sax.DTDHandler#notationDecl
111     */
112    public void notationDecl (String name, String publicId, String systemId)
113        throws SAXException
114    {
115        // no op
116    }
117    
118    
119    /**
120     * Receive notification of an unparsed entity declaration.
121     *
122     * <p>By default, do nothing.  Application writers may override this
123     * method in a subclass to keep track of the unparsed entities
124     * declared in a document.</p>
125     *
126     * @param name The entity name.
127     * @param publicId The entity public identifier, or null if not
128     *                 available.
129     * @param systemId The entity system identifier.
130     * @param notationName The name of the associated notation.
131     * @exception org.xml.sax.SAXException Any SAX exception, possibly
132     *            wrapping another exception.
133     * @see org.xml.sax.DTDHandler#unparsedEntityDecl
134     */
135    public void unparsedEntityDecl (String name, String publicId,
136                                    String systemId, String notationName)
137        throws SAXException
138    {
139        // no op
140    }
141    
142    
143
144    ////////////////////////////////////////////////////////////////////
145    // Default implementation of ContentHandler interface.
146    ////////////////////////////////////////////////////////////////////
147    
148    
149    /**
150     * Receive a Locator object for document events.
151     *
152     * <p>By default, do nothing.  Application writers may override this
153     * method in a subclass if they wish to store the locator for use
154     * with other document events.</p>
155     *
156     * @param locator A locator for all SAX document events.
157     * @see org.xml.sax.ContentHandler#setDocumentLocator
158     * @see org.xml.sax.Locator
159     */
160    public void setDocumentLocator (Locator locator)
161    {
162        // no op
163    }
164    
165    
166    /**
167     * Receive notification of the beginning of the document.
168     *
169     * <p>By default, do nothing.  Application writers may override this
170     * method in a subclass to take specific actions at the beginning
171     * of a document (such as allocating the root node of a tree or
172     * creating an output file).</p>
173     *
174     * @exception org.xml.sax.SAXException Any SAX exception, possibly
175     *            wrapping another exception.
176     * @see org.xml.sax.ContentHandler#startDocument
177     */
178    public void startDocument ()
179        throws SAXException
180    {
181        // no op
182    }
183    
184    
185    /**
186     * Receive notification of the end of the document.
187     *
188     * <p>By default, do nothing.  Application writers may override this
189     * method in a subclass to take specific actions at the end
190     * of a document (such as finalising a tree or closing an output
191     * file).</p>
192     *
193     * @exception org.xml.sax.SAXException Any SAX exception, possibly
194     *            wrapping another exception.
195     * @see org.xml.sax.ContentHandler#endDocument
196     */
197    public void endDocument ()
198        throws SAXException
199    {
200        // no op
201    }
202
203
204    /**
205     * Receive notification of the start of a Namespace mapping.
206     *
207     * <p>By default, do nothing.  Application writers may override this
208     * method in a subclass to take specific actions at the start of
209     * each Namespace prefix scope (such as storing the prefix mapping).</p>
210     *
211     * @param prefix The Namespace prefix being declared.
212     * @param uri The Namespace URI mapped to the prefix.
213     * @exception org.xml.sax.SAXException Any SAX exception, possibly
214     *            wrapping another exception.
215     * @see org.xml.sax.ContentHandler#startPrefixMapping
216     */
217    public void startPrefixMapping (String prefix, String uri)
218        throws SAXException
219    {
220        // no op
221    }
222
223
224    /**
225     * Receive notification of the end of a Namespace mapping.
226     *
227     * <p>By default, do nothing.  Application writers may override this
228     * method in a subclass to take specific actions at the end of
229     * each prefix mapping.</p>
230     *
231     * @param prefix The Namespace prefix being declared.
232     * @exception org.xml.sax.SAXException Any SAX exception, possibly
233     *            wrapping another exception.
234     * @see org.xml.sax.ContentHandler#endPrefixMapping
235     */
236    public void endPrefixMapping (String prefix)
237        throws SAXException
238    {
239        // no op
240    }
241    
242    
243    /**
244     * Receive notification of the start of an element.
245     *
246     * <p>By default, do nothing.  Application writers may override this
247     * method in a subclass to take specific actions at the start of
248     * each element (such as allocating a new tree node or writing
249     * output to a file).</p>
250     *
251     * @param name The element type name.
252     * @param attributes The specified or defaulted attributes.
253     * @exception org.xml.sax.SAXException Any SAX exception, possibly
254     *            wrapping another exception.
255     * @see org.xml.sax.ContentHandler#startElement
256     */
257    public void startElement (String uri, String localName,
258                              String qName, Attributes attributes)
259        throws SAXException
260    {
261        // no op
262    }
263    
264    
265    /**
266     * Receive notification of the end of an element.
267     *
268     * <p>By default, do nothing.  Application writers may override this
269     * method in a subclass to take specific actions at the end of
270     * each element (such as finalising a tree node or writing
271     * output to a file).</p>
272     *
273     * @param name The element type name.
274     * @param attributes The specified or defaulted attributes.
275     * @exception org.xml.sax.SAXException Any SAX exception, possibly
276     *            wrapping another exception.
277     * @see org.xml.sax.ContentHandler#endElement
278     */
279    public void endElement (String uri, String localName, String qName)
280        throws SAXException
281    {
282        // no op
283    }
284    
285    
286    /**
287     * Receive notification of character data inside an element.
288     *
289     * <p>By default, do nothing.  Application writers may override this
290     * method to take specific actions for each chunk of character data
291     * (such as adding the data to a node or buffer, or printing it to
292     * a file).</p>
293     *
294     * @param ch The characters.
295     * @param start The start position in the character array.
296     * @param length The number of characters to use from the
297     *               character array.
298     * @exception org.xml.sax.SAXException Any SAX exception, possibly
299     *            wrapping another exception.
300     * @see org.xml.sax.ContentHandler#characters
301     */
302    public void characters (char ch[], int start, int length)
303        throws SAXException
304    {
305        // no op
306    }
307    
308    
309    /**
310     * Receive notification of ignorable whitespace in element content.
311     *
312     * <p>By default, do nothing.  Application writers may override this
313     * method to take specific actions for each chunk of ignorable
314     * whitespace (such as adding data to a node or buffer, or printing
315     * it to a file).</p>
316     *
317     * @param ch The whitespace characters.
318     * @param start The start position in the character array.
319     * @param length The number of characters to use from the
320     *               character array.
321     * @exception org.xml.sax.SAXException Any SAX exception, possibly
322     *            wrapping another exception.
323     * @see org.xml.sax.ContentHandler#ignorableWhitespace
324     */
325    public void ignorableWhitespace (char ch[], int start, int length)
326        throws SAXException
327    {
328        // no op
329    }
330    
331    
332    /**
333     * Receive notification of a processing instruction.
334     *
335     * <p>By default, do nothing.  Application writers may override this
336     * method in a subclass to take specific actions for each
337     * processing instruction, such as setting status variables or
338     * invoking other methods.</p>
339     *
340     * @param target The processing instruction target.
341     * @param data The processing instruction data, or null if
342     *             none is supplied.
343     * @exception org.xml.sax.SAXException Any SAX exception, possibly
344     *            wrapping another exception.
345     * @see org.xml.sax.ContentHandler#processingInstruction
346     */
347    public void processingInstruction (String target, String data)
348        throws SAXException
349    {
350        // no op
351    }
352
353
354    /**
355     * Receive notification of a skipped entity.
356     *
357     * <p>By default, do nothing.  Application writers may override this
358     * method in a subclass to take specific actions for each
359     * processing instruction, such as setting status variables or
360     * invoking other methods.</p>
361     *
362     * @param name The name of the skipped entity.
363     * @exception org.xml.sax.SAXException Any SAX exception, possibly
364     *            wrapping another exception.
365     * @see org.xml.sax.ContentHandler#processingInstruction
366     */
367    public void skippedEntity (String name)
368        throws SAXException
369    {
370        // no op
371    }
372    
373    
374
375    ////////////////////////////////////////////////////////////////////
376    // Default implementation of the ErrorHandler interface.
377    ////////////////////////////////////////////////////////////////////
378    
379    
380    /**
381     * Receive notification of a parser warning.
382     *
383     * <p>The default implementation does nothing.  Application writers
384     * may override this method in a subclass to take specific actions
385     * for each warning, such as inserting the message in a log file or
386     * printing it to the console.</p>
387     *
388     * @param e The warning information encoded as an exception.
389     * @exception org.xml.sax.SAXException Any SAX exception, possibly
390     *            wrapping another exception.
391     * @see org.xml.sax.ErrorHandler#warning
392     * @see org.xml.sax.SAXParseException
393     */
394    public void warning (SAXParseException e)
395        throws SAXException
396    {
397        // no op
398    }
399    
400    
401    /**
402     * Receive notification of a recoverable parser error.
403     *
404     * <p>The default implementation does nothing.  Application writers
405     * may override this method in a subclass to take specific actions
406     * for each error, such as inserting the message in a log file or
407     * printing it to the console.</p>
408     *
409     * @param e The warning information encoded as an exception.
410     * @exception org.xml.sax.SAXException Any SAX exception, possibly
411     *            wrapping another exception.
412     * @see org.xml.sax.ErrorHandler#warning
413     * @see org.xml.sax.SAXParseException
414     */
415    public void error (SAXParseException e)
416        throws SAXException
417    {
418        // no op
419    }
420    
421    
422    /**
423     * Report a fatal XML parsing error.
424     *
425     * <p>The default implementation throws a SAXParseException.
426     * Application writers may override this method in a subclass if
427     * they need to take specific actions for each fatal error (such as
428     * collecting all of the errors into a single report): in any case,
429     * the application must stop all regular processing when this
430     * method is invoked, since the document is no longer reliable, and
431     * the parser may no longer report parsing events.</p>
432     *
433     * @param e The error information encoded as an exception.
434     * @exception org.xml.sax.SAXException Any SAX exception, possibly
435     *            wrapping another exception.
436     * @see org.xml.sax.ErrorHandler#fatalError
437     * @see org.xml.sax.SAXParseException
438     */
439    public void fatalError (SAXParseException e)
440        throws SAXException
441    {
442        throw e;
443    }
444    
445}
446
447// end of DefaultHandler.java