View Javadoc

1   // SAX default handler base class.
2   // http://www.saxproject.org
3   // No warranty; no copyright -- use this as you will.
4   // $Id: HandlerBase.java,v 1.5 2004/03/19 20:17:54 maartenc Exp $
5   
6   package org.xml.sax;
7   
8   /***
9    * Default base class for handlers.
10   *
11   * <blockquote>
12   * <em>This module, both source code and documentation, is in the
13   * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
14   * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
15   * for further information.
16   * </blockquote>
17   *
18   * <p>This class implements the default behaviour for four SAX1
19   * interfaces: EntityResolver, DTDHandler, DocumentHandler,
20   * and ErrorHandler.  It is now obsolete, but is included in SAX2 to
21   * support legacy SAX1 applications.  SAX2 applications should use
22   * the {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}
23   * class instead.</p>
24   *
25   * <p>Application writers can extend this class when they need to
26   * implement only part of an interface; parser writers can
27   * instantiate this class to provide default handlers when the
28   * application has not supplied its own.</p>
29   *
30   * <p>Note that the use of this class is optional.</p>
31   *
32   * @deprecated This class works with the deprecated
33   *             {@link org.xml.sax.DocumentHandler DocumentHandler}
34   *             interface.  It has been replaced by the SAX2
35   *             {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}
36   *             class.
37   * @since SAX 1.0
38   * @author David Megginson
39   * @version 2.0.1 (sax2r2)
40   * @see org.xml.sax.EntityResolver
41   * @see org.xml.sax.DTDHandler
42   * @see org.xml.sax.DocumentHandler
43   * @see org.xml.sax.ErrorHandler
44   */
45  public class HandlerBase
46      implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler
47  {
48      
49  
50      ////////////////////////////////////////////////////////////////////
51      // Default implementation of the EntityResolver interface.
52      ////////////////////////////////////////////////////////////////////
53      
54      /***
55       * Resolve an external entity.
56       *
57       * <p>Always return null, so that the parser will use the system
58       * identifier provided in the XML document.  This method implements
59       * the SAX default behaviour: application writers can override it
60       * in a subclass to do special translations such as catalog lookups
61       * or URI redirection.</p>
62       *
63       * @param publicId The public identifer, or null if none is
64       *                 available.
65       * @param systemId The system identifier provided in the XML 
66       *                 document.
67       * @return The new input source, or null to require the
68       *         default behaviour.
69       * @exception org.xml.sax.SAXException Any SAX exception, possibly
70       *            wrapping another exception.
71       * @see org.xml.sax.EntityResolver#resolveEntity
72       */
73      public InputSource resolveEntity (String publicId, String systemId)
74  	throws SAXException
75      {
76  	return null;
77      }
78      
79      
80  
81      ////////////////////////////////////////////////////////////////////
82      // Default implementation of DTDHandler interface.
83      ////////////////////////////////////////////////////////////////////
84      
85      
86      /***
87       * Receive notification of a notation declaration.
88       *
89       * <p>By default, do nothing.  Application writers may override this
90       * method in a subclass if they wish to keep track of the notations
91       * declared in a document.</p>
92       *
93       * @param name The notation name.
94       * @param publicId The notation public identifier, or null if not
95       *                 available.
96       * @param systemId The notation system identifier.
97       * @see org.xml.sax.DTDHandler#notationDecl
98       */
99      public void notationDecl (String name, String publicId, String systemId)
100     {
101 	// no op
102     }
103     
104     
105     /***
106      * Receive notification of an unparsed entity declaration.
107      *
108      * <p>By default, do nothing.  Application writers may override this
109      * method in a subclass to keep track of the unparsed entities
110      * declared in a document.</p>
111      *
112      * @param name The entity name.
113      * @param publicId The entity public identifier, or null if not
114      *                 available.
115      * @param systemId The entity system identifier.
116      * @param notationName The name of the associated notation.
117      * @see org.xml.sax.DTDHandler#unparsedEntityDecl
118      */
119     public void unparsedEntityDecl (String name, String publicId,
120 				    String systemId, String notationName)
121     {
122 	// no op
123     }
124     
125     
126 
127     ////////////////////////////////////////////////////////////////////
128     // Default implementation of DocumentHandler interface.
129     ////////////////////////////////////////////////////////////////////
130     
131     
132     /***
133      * Receive a Locator object for document events.
134      *
135      * <p>By default, do nothing.  Application writers may override this
136      * method in a subclass if they wish to store the locator for use
137      * with other document events.</p>
138      *
139      * @param locator A locator for all SAX document events.
140      * @see org.xml.sax.DocumentHandler#setDocumentLocator
141      * @see org.xml.sax.Locator
142      */
143     public void setDocumentLocator (Locator locator)
144     {
145 	// no op
146     }
147     
148     
149     /***
150      * Receive notification of the beginning of the document.
151      *
152      * <p>By default, do nothing.  Application writers may override this
153      * method in a subclass to take specific actions at the beginning
154      * of a document (such as allocating the root node of a tree or
155      * creating an output file).</p>
156      *
157      * @exception org.xml.sax.SAXException Any SAX exception, possibly
158      *            wrapping another exception.
159      * @see org.xml.sax.DocumentHandler#startDocument
160      */
161     public void startDocument ()
162 	throws SAXException
163     {
164 	// no op
165     }
166     
167     
168     /***
169      * Receive notification of the end of the document.
170      *
171      * <p>By default, do nothing.  Application writers may override this
172      * method in a subclass to take specific actions at the beginning
173      * of a document (such as finalising a tree or closing an output
174      * file).</p>
175      *
176      * @exception org.xml.sax.SAXException Any SAX exception, possibly
177      *            wrapping another exception.
178      * @see org.xml.sax.DocumentHandler#endDocument
179      */
180     public void endDocument ()
181 	throws SAXException
182     {
183 	// no op
184     }
185     
186     
187     /***
188      * Receive notification of the start of an element.
189      *
190      * <p>By default, do nothing.  Application writers may override this
191      * method in a subclass to take specific actions at the start of
192      * each element (such as allocating a new tree node or writing
193      * output to a file).</p>
194      *
195      * @param name The element type name.
196      * @param attributes The specified or defaulted attributes.
197      * @exception org.xml.sax.SAXException Any SAX exception, possibly
198      *            wrapping another exception.
199      * @see org.xml.sax.DocumentHandler#startElement
200      */
201     public void startElement (String name, AttributeList attributes)
202 	throws SAXException
203     {
204 	// no op
205     }
206     
207     
208     /***
209      * Receive notification of the end of an element.
210      *
211      * <p>By default, do nothing.  Application writers may override this
212      * method in a subclass to take specific actions at the end of
213      * each element (such as finalising a tree node or writing
214      * output to a file).</p>
215      *
216      * @param name The element type name.
217      * @param attributes The specified or defaulted attributes.
218      * @exception org.xml.sax.SAXException Any SAX exception, possibly
219      *            wrapping another exception.
220      * @see org.xml.sax.DocumentHandler#endElement
221      */
222     public void endElement (String name)
223 	throws SAXException
224     {
225 	// no op
226     }
227     
228     
229     /***
230      * Receive notification of character data inside an element.
231      *
232      * <p>By default, do nothing.  Application writers may override this
233      * method to take specific actions for each chunk of character data
234      * (such as adding the data to a node or buffer, or printing it to
235      * a file).</p>
236      *
237      * @param ch The characters.
238      * @param start The start position in the character array.
239      * @param length The number of characters to use from the
240      *               character array.
241      * @exception org.xml.sax.SAXException Any SAX exception, possibly
242      *            wrapping another exception.
243      * @see org.xml.sax.DocumentHandler#characters
244      */
245     public void characters (char ch[], int start, int length)
246 	throws SAXException
247     {
248 	// no op
249     }
250     
251     
252     /***
253      * Receive notification of ignorable whitespace in element content.
254      *
255      * <p>By default, do nothing.  Application writers may override this
256      * method to take specific actions for each chunk of ignorable
257      * whitespace (such as adding data to a node or buffer, or printing
258      * it to a file).</p>
259      *
260      * @param ch The whitespace characters.
261      * @param start The start position in the character array.
262      * @param length The number of characters to use from the
263      *               character array.
264      * @exception org.xml.sax.SAXException Any SAX exception, possibly
265      *            wrapping another exception.
266      * @see org.xml.sax.DocumentHandler#ignorableWhitespace
267      */
268     public void ignorableWhitespace (char ch[], int start, int length)
269 	throws SAXException
270     {
271 	// no op
272     }
273     
274     
275     /***
276      * Receive notification of a processing instruction.
277      *
278      * <p>By default, do nothing.  Application writers may override this
279      * method in a subclass to take specific actions for each
280      * processing instruction, such as setting status variables or
281      * invoking other methods.</p>
282      *
283      * @param target The processing instruction target.
284      * @param data The processing instruction data, or null if
285      *             none is supplied.
286      * @exception org.xml.sax.SAXException Any SAX exception, possibly
287      *            wrapping another exception.
288      * @see org.xml.sax.DocumentHandler#processingInstruction
289      */
290     public void processingInstruction (String target, String data)
291 	throws SAXException
292     {
293 	// no op
294     }
295     
296     
297 
298     ////////////////////////////////////////////////////////////////////
299     // Default implementation of the ErrorHandler interface.
300     ////////////////////////////////////////////////////////////////////
301     
302     
303     /***
304      * Receive notification of a parser warning.
305      *
306      * <p>The default implementation does nothing.  Application writers
307      * may override this method in a subclass to take specific actions
308      * for each warning, such as inserting the message in a log file or
309      * printing it to the console.</p>
310      *
311      * @param e The warning information encoded as an exception.
312      * @exception org.xml.sax.SAXException Any SAX exception, possibly
313      *            wrapping another exception.
314      * @see org.xml.sax.ErrorHandler#warning
315      * @see org.xml.sax.SAXParseException
316      */
317     public void warning (SAXParseException e)
318 	throws SAXException
319     {
320 	// no op
321     }
322     
323     
324     /***
325      * Receive notification of a recoverable parser error.
326      *
327      * <p>The default implementation does nothing.  Application writers
328      * may override this method in a subclass to take specific actions
329      * for each error, such as inserting the message in a log file or
330      * printing it to the console.</p>
331      *
332      * @param e The warning information encoded as an exception.
333      * @exception org.xml.sax.SAXException Any SAX exception, possibly
334      *            wrapping another exception.
335      * @see org.xml.sax.ErrorHandler#warning
336      * @see org.xml.sax.SAXParseException
337      */
338     public void error (SAXParseException e)
339 	throws SAXException
340     {
341 	// no op
342     }
343     
344     
345     /***
346      * Report a fatal XML parsing error.
347      *
348      * <p>The default implementation throws a SAXParseException.
349      * Application writers may override this method in a subclass if
350      * they need to take specific actions for each fatal error (such as
351      * collecting all of the errors into a single report): in any case,
352      * the application must stop all regular processing when this
353      * method is invoked, since the document is no longer reliable, and
354      * the parser may no longer report parsing events.</p>
355      *
356      * @param e The error information encoded as an exception.
357      * @exception org.xml.sax.SAXException Any SAX exception, possibly
358      *            wrapping another exception.
359      * @see org.xml.sax.ErrorHandler#fatalError
360      * @see org.xml.sax.SAXParseException
361      */
362     public void fatalError (SAXParseException e)
363 	throws SAXException
364     {
365 	throw e;
366     }
367     
368 }
369 
370 // end of HandlerBase.java