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