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.1 2004/12/23 22:38:42 mark Exp $
005    
006    package 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     */
045    public 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 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 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