Source Home >> Java Source 1.6.0 >> org.xml.sax.HandlerBase V 0.09

001// SAX default handler base class.
002// http://www.saxproject.org
003// No warranty; no copyright -- use this as you will.
004// $Id: HandlerBase.java,v 1.2 2005/06/10 03:50:47 jeffsuttor Exp $
005
006package org.xml.sax;
007
008/**
009 * Default base class for handlers.
010 *
011 * <blockquote>
012 * <em>This module, both source code and documentation, is in the
013 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
014 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
015 * for further information.
016 * </blockquote>
017 *
018 * <p>This class implements the default behaviour for four SAX1
019 * interfaces: EntityResolver, DTDHandler, DocumentHandler,
020 * and ErrorHandler.  It is now obsolete, but is included in SAX2 to
021 * support legacy SAX1 applications.  SAX2 applications should use
022 * the {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}
023 * class instead.</p>
024 *
025 * <p>Application writers can extend this class when they need to
026 * implement only part of an interface; parser writers can
027 * instantiate this class to provide default handlers when the
028 * application has not supplied its own.</p>
029 *
030 * <p>Note that the use of this class is optional.</p>
031 *
032 * @deprecated This class works with the deprecated
033 *             {@link org.xml.sax.DocumentHandler DocumentHandler}
034 *             interface.  It has been replaced by the SAX2
035 *             {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}
036 *             class.
037 * @since SAX 1.0
038 * @author David Megginson
039 * @version 2.0.1 (sax2r2)
040 * @see org.xml.sax.EntityResolver
041 * @see org.xml.sax.DTDHandler
042 * @see org.xml.sax.DocumentHandler
043 * @see org.xml.sax.ErrorHandler
044 */
045public class HandlerBase
046    implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler
047{
048    
049
050    ////////////////////////////////////////////////////////////////////
051    // Default implementation of the EntityResolver interface.
052    ////////////////////////////////////////////////////////////////////
053    
054    /**
055     * Resolve an external entity.
056     *
057     * <p>Always return null, so that the parser will use the system
058     * identifier provided in the XML document.  This method implements
059     * the SAX default behaviour: application writers can override it
060     * in a subclass to do special translations such as catalog lookups
061     * or URI redirection.</p>
062     *
063     * @param publicId The public identifer, or null if none is
064     *                 available.
065     * @param systemId The system identifier provided in the XML 
066     *                 document.
067     * @return The new input source, or null to require the
068     *         default behaviour.
069     * @exception org.xml.sax.SAXException Any SAX exception, possibly
070     *            wrapping another exception.
071     * @see org.xml.sax.EntityResolver#resolveEntity
072     */
073    public InputSource resolveEntity (String publicId, String systemId)
074	throws SAXException
075    {
076	return null;
077    }
078    
079    
080
081    ////////////////////////////////////////////////////////////////////
082    // Default implementation of DTDHandler interface.
083    ////////////////////////////////////////////////////////////////////
084    
085    
086    /**
087     * Receive notification of a notation declaration.
088     *
089     * <p>By default, do nothing.  Application writers may override this
090     * method in a subclass if they wish to keep track of the notations
091     * declared in a document.</p>
092     *
093     * @param name The notation name.
094     * @param publicId The notation public identifier, or null if not
095     *                 available.
096     * @param systemId The notation system identifier.
097     * @see org.xml.sax.DTDHandler#notationDecl
098     */
099    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 end
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 name
217     * @exception org.xml.sax.SAXException Any SAX exception, possibly
218     *            wrapping another exception.
219     * @see org.xml.sax.DocumentHandler#endElement
220     */
221    public void endElement (String name)
222	throws SAXException
223    {
224	// no op
225    }
226    
227    
228    /**
229     * Receive notification of character data inside an element.
230     *
231     * <p>By default, do nothing.  Application writers may override this
232     * method to take specific actions for each chunk of character data
233     * (such as adding the data to a node or buffer, or printing it to
234     * a file).</p>
235     *
236     * @param ch The characters.
237     * @param start The start position in the character array.
238     * @param length The number of characters to use from the
239     *               character array.
240     * @exception org.xml.sax.SAXException Any SAX exception, possibly
241     *            wrapping another exception.
242     * @see org.xml.sax.DocumentHandler#characters
243     */
244    public void characters (char ch[], int start, int length)
245	throws SAXException
246    {
247	// no op
248    }
249    
250    
251    /**
252     * Receive notification of ignorable whitespace in element content.
253     *
254     * <p>By default, do nothing.  Application writers may override this
255     * method to take specific actions for each chunk of ignorable
256     * whitespace (such as adding data to a node or buffer, or printing
257     * it to a file).</p>
258     *
259     * @param ch The whitespace characters.
260     * @param start The start position in the character array.
261     * @param length The number of characters to use from the
262     *               character array.
263     * @exception org.xml.sax.SAXException Any SAX exception, possibly
264     *            wrapping another exception.
265     * @see org.xml.sax.DocumentHandler#ignorableWhitespace
266     */
267    public void ignorableWhitespace (char ch[], int start, int length)
268	throws SAXException
269    {
270	// no op
271    }
272    
273    
274    /**
275     * Receive notification of a processing instruction.
276     *
277     * <p>By default, do nothing.  Application writers may override this
278     * method in a subclass to take specific actions for each
279     * processing instruction, such as setting status variables or
280     * invoking other methods.</p>
281     *
282     * @param target The processing instruction target.
283     * @param data The processing instruction data, or null if
284     *             none is supplied.
285     * @exception org.xml.sax.SAXException Any SAX exception, possibly
286     *            wrapping another exception.
287     * @see org.xml.sax.DocumentHandler#processingInstruction
288     */
289    public void processingInstruction (String target, String data)
290	throws SAXException
291    {
292	// no op
293    }
294    
295    
296
297    ////////////////////////////////////////////////////////////////////
298    // Default implementation of the ErrorHandler interface.
299    ////////////////////////////////////////////////////////////////////
300    
301    
302    /**
303     * Receive notification of a parser warning.
304     *
305     * <p>The default implementation does nothing.  Application writers
306     * may override this method in a subclass to take specific actions
307     * for each warning, such as inserting the message in a log file or
308     * printing it to the console.</p>
309     *
310     * @param e The warning information encoded as an exception.
311     * @exception org.xml.sax.SAXException Any SAX exception, possibly
312     *            wrapping another exception.
313     * @see org.xml.sax.ErrorHandler#warning
314     * @see org.xml.sax.SAXParseException
315     */
316    public void warning (SAXParseException e)
317	throws SAXException
318    {
319	// no op
320    }
321    
322    
323    /**
324     * Receive notification of a recoverable parser error.
325     *
326     * <p>The default implementation does nothing.  Application writers
327     * may override this method in a subclass to take specific actions
328     * for each error, such as inserting the message in a log file or
329     * printing it to the console.</p>
330     *
331     * @param e The warning information encoded as an exception.
332     * @exception org.xml.sax.SAXException Any SAX exception, possibly
333     *            wrapping another exception.
334     * @see org.xml.sax.ErrorHandler#warning
335     * @see org.xml.sax.SAXParseException
336     */
337    public void error (SAXParseException e)
338	throws SAXException
339    {
340	// no op
341    }
342    
343    
344    /**
345     * Report a fatal XML parsing error.
346     *
347     * <p>The default implementation throws a SAXParseException.
348     * Application writers may override this method in a subclass if
349     * they need to take specific actions for each fatal error (such as
350     * collecting all of the errors into a single report): in any case,
351     * the application must stop all regular processing when this
352     * method is invoked, since the document is no longer reliable, and
353     * the parser may no longer report parsing events.</p>
354     *
355     * @param e The error information encoded as an exception.
356     * @exception org.xml.sax.SAXException Any SAX exception, possibly
357     *            wrapping another exception.
358     * @see org.xml.sax.ErrorHandler#fatalError
359     * @see org.xml.sax.SAXParseException
360     */
361    public void fatalError (SAXParseException e)
362	throws SAXException
363    {
364	throw e;
365    }
366    
367}
368
369// end of HandlerBase.java