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    
007    package org.xml.sax.helpers;
008    
009    import java.io.IOException;
010    
011    import org.xml.sax.InputSource;
012    import org.xml.sax.Locator;
013    import org.xml.sax.Attributes;
014    import org.xml.sax.EntityResolver;
015    import org.xml.sax.DTDHandler;
016    import org.xml.sax.ContentHandler;
017    import org.xml.sax.ErrorHandler;
018    import org.xml.sax.SAXException;
019    import 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     */
059    public 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