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.7 2004/04/26 17:34:34 dmegginson 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 @Deprecated
46 public class HandlerBase
47     implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler
48 {
49 
50 
51     ////////////////////////////////////////////////////////////////////
52     // Default implementation of the EntityResolver interface.
53     ////////////////////////////////////////////////////////////////////
54 
55     /**
56      * Resolve an external entity.
57      *
58      * <p>Always return null, so that the parser will use the system
59      * identifier provided in the XML document.  This method implements
60      * the SAX default behaviour: application writers can override it
61      * in a subclass to do special translations such as catalog lookups
62      * or URI redirection.</p>
63      *
64      * @param publicId The public identifer, or null if none is
65      *                 available.
66      * @param systemId The system identifier provided in the XML
67      *                 document.
68      * @return The new input source, or null to require the
69      *         default behaviour.
70      * @exception org.xml.sax.SAXException Any SAX exception, possibly
71      *            wrapping another exception.
72      * @see org.xml.sax.EntityResolver#resolveEntity
73      */
resolveEntity(String publicId, String systemId)74     public InputSource resolveEntity (String publicId, String systemId)
75     throws SAXException
76     {
77     return null;
78     }
79 
80 
81 
82     ////////////////////////////////////////////////////////////////////
83     // Default implementation of DTDHandler interface.
84     ////////////////////////////////////////////////////////////////////
85 
86 
87     /**
88      * Receive notification of a notation declaration.
89      *
90      * <p>By default, do nothing.  Application writers may override this
91      * method in a subclass if they wish to keep track of the notations
92      * declared in a document.</p>
93      *
94      * @param name The notation name.
95      * @param publicId The notation public identifier, or null if not
96      *                 available.
97      * @param systemId The notation system identifier.
98      * @see org.xml.sax.DTDHandler#notationDecl
99      */
notationDecl(String name, String publicId, String systemId)100     public void notationDecl (String name, String publicId, String systemId)
101     {
102     // no op
103     }
104 
105 
106     /**
107      * Receive notification of an unparsed entity declaration.
108      *
109      * <p>By default, do nothing.  Application writers may override this
110      * method in a subclass to keep track of the unparsed entities
111      * declared in a document.</p>
112      *
113      * @param name The entity name.
114      * @param publicId The entity public identifier, or null if not
115      *                 available.
116      * @param systemId The entity system identifier.
117      * @param notationName The name of the associated notation.
118      * @see org.xml.sax.DTDHandler#unparsedEntityDecl
119      */
unparsedEntityDecl(String name, String publicId, String systemId, String notationName)120     public void unparsedEntityDecl (String name, String publicId,
121                     String systemId, String notationName)
122     {
123     // no op
124     }
125 
126 
127 
128     ////////////////////////////////////////////////////////////////////
129     // Default implementation of DocumentHandler interface.
130     ////////////////////////////////////////////////////////////////////
131 
132 
133     /**
134      * Receive a Locator object for document events.
135      *
136      * <p>By default, do nothing.  Application writers may override this
137      * method in a subclass if they wish to store the locator for use
138      * with other document events.</p>
139      *
140      * @param locator A locator for all SAX document events.
141      * @see org.xml.sax.DocumentHandler#setDocumentLocator
142      * @see org.xml.sax.Locator
143      */
setDocumentLocator(Locator locator)144     public void setDocumentLocator (Locator locator)
145     {
146     // no op
147     }
148 
149 
150     /**
151      * Receive notification of the beginning of the document.
152      *
153      * <p>By default, do nothing.  Application writers may override this
154      * method in a subclass to take specific actions at the beginning
155      * of a document (such as allocating the root node of a tree or
156      * creating an output file).</p>
157      *
158      * @exception org.xml.sax.SAXException Any SAX exception, possibly
159      *            wrapping another exception.
160      * @see org.xml.sax.DocumentHandler#startDocument
161      */
startDocument()162     public void startDocument ()
163     throws SAXException
164     {
165     // no op
166     }
167 
168 
169     /**
170      * Receive notification of the end of the document.
171      *
172      * <p>By default, do nothing.  Application writers may override this
173      * method in a subclass to take specific actions at the beginning
174      * of a document (such as finalising a tree or closing an output
175      * file).</p>
176      *
177      * @exception org.xml.sax.SAXException Any SAX exception, possibly
178      *            wrapping another exception.
179      * @see org.xml.sax.DocumentHandler#endDocument
180      */
endDocument()181     public void endDocument ()
182     throws SAXException
183     {
184     // no op
185     }
186 
187 
188     /**
189      * Receive notification of the start of an element.
190      *
191      * <p>By default, do nothing.  Application writers may override this
192      * method in a subclass to take specific actions at the start of
193      * each element (such as allocating a new tree node or writing
194      * output to a file).</p>
195      *
196      * @param name The element type name.
197      * @param attributes The specified or defaulted attributes.
198      * @exception org.xml.sax.SAXException Any SAX exception, possibly
199      *            wrapping another exception.
200      * @see org.xml.sax.DocumentHandler#startElement
201      */
startElement(String name, AttributeList attributes)202     public void startElement (String name, AttributeList attributes)
203     throws SAXException
204     {
205     // no op
206     }
207 
208 
209     /**
210      * Receive notification of the end of an element.
211      *
212      * <p>By default, do nothing.  Application writers may override this
213      * method in a subclass to take specific actions at the end of
214      * each element (such as finalising a tree node or writing
215      * output to a file).</p>
216      *
217      * @param name the element name
218      * @exception org.xml.sax.SAXException Any SAX exception, possibly
219      *            wrapping another exception.
220      * @see org.xml.sax.DocumentHandler#endElement
221      */
endElement(String name)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      */
characters(char ch[], int start, int length)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      */
ignorableWhitespace(char ch[], int start, int length)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      */
processingInstruction(String target, String data)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      */
warning(SAXParseException e)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      */
error(SAXParseException e)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      */
fatalError(SAXParseException e)362     public void fatalError (SAXParseException e)
363     throws SAXException
364     {
365     throw e;
366     }
367 
368 }
369 
370 // end of HandlerBase.java
371