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