/*

 * Copyright 2000-2006 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

// SAX default handler base class.

// http://www.saxproject.org

// No warranty; no copyright -- use this as you will.

// $Id: HandlerBase.java,v 1.2 2005/06/10 03:50:47 jeffsuttor Exp $

package org.xml.sax;

/**

 * Default base class for handlers.

 *

 * <blockquote>

 * <em>This module, both source code and documentation, is in the

 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>

 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>

 * for further information.

 * </blockquote>

 *

 * <p>This class implements the default behaviour for four SAX1

 * interfaces: EntityResolver, DTDHandler, DocumentHandler,

 * and ErrorHandler.  It is now obsolete, but is included in SAX2 to

 * support legacy SAX1 applications.  SAX2 applications should use

 * the {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}

 * class instead.</p>

 *

 * <p>Application writers can extend this class when they need to

 * implement only part of an interface; parser writers can

 * instantiate this class to provide default handlers when the

 * application has not supplied its own.</p>

 *

 * <p>Note that the use of this class is optional.</p>

 *

 * @deprecated This class works with the deprecated

 *             {@link org.xml.sax.DocumentHandler DocumentHandler}

 *             interface.  It has been replaced by the SAX2

 *             {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}

 *             class.

 * @since SAX 1.0

 * @author David Megginson

 * @see org.xml.sax.EntityResolver

 * @see org.xml.sax.DTDHandler

 * @see org.xml.sax.DocumentHandler

 * @see org.xml.sax.ErrorHandler

 */

public class HandlerBase

    implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler

{

    ////////////////////////////////////////////////////////////////////

    // Default implementation of the EntityResolver interface.

    ////////////////////////////////////////////////////////////////////

    /**

     * Resolve an external entity.

     *

     * <p>Always return null, so that the parser will use the system

     * identifier provided in the XML document.  This method implements

     * the SAX default behaviour: application writers can override it

     * in a subclass to do special translations such as catalog lookups

     * or URI redirection.</p>

     *

     * @param publicId The public identifer, or null if none is

     *                 available.

     * @param systemId The system identifier provided in the XML

     *                 document.

     * @return The new input source, or null to require the

     *         default behaviour.

     * @exception org.xml.sax.SAXException Any SAX exception, possibly

     *            wrapping another exception.

     * @see org.xml.sax.EntityResolver#resolveEntity

     */

    public InputSource resolveEntity (String publicId, String systemId)

        throws SAXException

    {

        return null;

    }

    ////////////////////////////////////////////////////////////////////

    // Default implementation of DTDHandler interface.

    ////////////////////////////////////////////////////////////////////

    /**

     * Receive notification of a notation declaration.

     *

     * <p>By default, do nothing.  Application writers may override this

     * method in a subclass if they wish to keep track of the notations

     * declared in a document.</p>

     *

     * @param name The notation name.

     * @param publicId The notation public identifier, or null if not

     *                 available.

     * @param systemId The notation system identifier.

     * @see org.xml.sax.DTDHandler#notationDecl

     */

    public void notationDecl (String name, String publicId, String systemId)

    {

        // no op

    }

    /**

     * Receive notification of an unparsed entity declaration.

     *

     * <p>By default, do nothing.  Application writers may override this

     * method in a subclass to keep track of the unparsed entities

     * declared in a document.</p>

     *

     * @param name The entity name.

     * @param publicId The entity public identifier, or null if not

     *                 available.

     * @param systemId The entity system identifier.

     * @param notationName The name of the associated notation.

     * @see org.xml.sax.DTDHandler#unparsedEntityDecl

     */

    public void unparsedEntityDecl (String name, String publicId,

                                    String systemId, String notationName)

    {

        // no op

    }

    ////////////////////////////////////////////////////////////////////

    // Default implementation of DocumentHandler interface.

    ////////////////////////////////////////////////////////////////////

    /**

     * Receive a Locator object for document events.

     *

     * <p>By default, do nothing.  Application writers may override this

     * method in a subclass if they wish to store the locator for use

     * with other document events.</p>

     *

     * @param locator A locator for all SAX document events.

     * @see org.xml.sax.DocumentHandler#setDocumentLocator

     * @see org.xml.sax.Locator

     */

    public void setDocumentLocator (Locator locator)

    {

        // no op

    }

    /**

     * Receive notification of the beginning of the document.

     *

     * <p>By default, do nothing.  Application writers may override this

     * method in a subclass to take specific actions at the beginning

     * of a document (such as allocating the root node of a tree or

     * creating an output file).</p>

     *

     * @exception org.xml.sax.SAXException Any SAX exception, possibly

     *            wrapping another exception.

     * @see org.xml.sax.DocumentHandler#startDocument

     */

    public void startDocument ()

        throws SAXException

    {

        // no op

    }

    /**

     * Receive notification of the end of the document.

     *

     * <p>By default, do nothing.  Application writers may override this

     * method in a subclass to take specific actions at the end

     * of a document (such as finalising a tree or closing an output

     * file).</p>

     *

     * @exception org.xml.sax.SAXException Any SAX exception, possibly

     *            wrapping another exception.

     * @see org.xml.sax.DocumentHandler#endDocument

     */

    public void endDocument ()

        throws SAXException

    {

        // no op

    }

    /**

     * Receive notification of the start of an element.

     *

     * <p>By default, do nothing.  Application writers may override this

     * method in a subclass to take specific actions at the start of

     * each element (such as allocating a new tree node or writing

     * output to a file).</p>

     *

     * @param name The element type name.

     * @param attributes The specified or defaulted attributes.

     * @exception org.xml.sax.SAXException Any SAX exception, possibly

     *            wrapping another exception.

     * @see org.xml.sax.DocumentHandler#startElement

     */

    public void startElement (String name, AttributeList attributes)

        throws SAXException

    {

        // no op

    }

    /**

     * Receive notification of the end of an element.

     *

     * <p>By default, do nothing.  Application writers may override this

     * method in a subclass to take specific actions at the end of

     * each element (such as finalising a tree node or writing

     * output to a file).</p>

     *

     * @param name the element name

     * @exception org.xml.sax.SAXException Any SAX exception, possibly

     *            wrapping another exception.

     * @see org.xml.sax.DocumentHandler#endElement

     */

    public void endElement (String name)

        throws SAXException

    {

        // no op

    }

    /**

     * Receive notification of character data inside an element.

     *

     * <p>By default, do nothing.  Application writers may override this

     * method to take specific actions for each chunk of character data

     * (such as adding the data to a node or buffer, or printing it to

     * a file).</p>

     *

     * @param ch The characters.

     * @param start The start position in the character array.

     * @param length The number of characters to use from the

     *               character array.

     * @exception org.xml.sax.SAXException Any SAX exception, possibly

     *            wrapping another exception.

     * @see org.xml.sax.DocumentHandler#characters

     */

    public void characters (char ch[], int start, int length)

        throws SAXException

    {

        // no op

    }

    /**

     * Receive notification of ignorable whitespace in element content.

     *

     * <p>By default, do nothing.  Application writers may override this

     * method to take specific actions for each chunk of ignorable

     * whitespace (such as adding data to a node or buffer, or printing

     * it to a file).</p>

     *

     * @param ch The whitespace characters.

     * @param start The start position in the character array.

     * @param length The number of characters to use from the

     *               character array.

     * @exception org.xml.sax.SAXException Any SAX exception, possibly

     *            wrapping another exception.

     * @see org.xml.sax.DocumentHandler#ignorableWhitespace

     */

    public void ignorableWhitespace (char ch[], int start, int length)

        throws SAXException

    {

        // no op

    }

    /**

     * Receive notification of a processing instruction.

     *

     * <p>By default, do nothing.  Application writers may override this

     * method in a subclass to take specific actions for each

     * processing instruction, such as setting status variables or

     * invoking other methods.</p>

     *

     * @param target The processing instruction target.

     * @param data The processing instruction data, or null if

     *             none is supplied.

     * @exception org.xml.sax.SAXException Any SAX exception, possibly

     *            wrapping another exception.

     * @see org.xml.sax.DocumentHandler#processingInstruction

     */

    public void processingInstruction (String target, String data)

        throws SAXException

    {

        // no op

    }

    ////////////////////////////////////////////////////////////////////

    // Default implementation of the ErrorHandler interface.

    ////////////////////////////////////////////////////////////////////

    /**

     * Receive notification of a parser warning.

     *

     * <p>The default implementation does nothing.  Application writers

     * may override this method in a subclass to take specific actions

     * for each warning, such as inserting the message in a log file or

     * printing it to the console.</p>

     *

     * @param e The warning information encoded as an exception.

     * @exception org.xml.sax.SAXException Any SAX exception, possibly

     *            wrapping another exception.

     * @see org.xml.sax.ErrorHandler#warning

     * @see org.xml.sax.SAXParseException

     */

    public void warning (SAXParseException e)

        throws SAXException

    {

        // no op

    }

    /**

     * Receive notification of a recoverable parser error.

     *

     * <p>The default implementation does nothing.  Application writers

     * may override this method in a subclass to take specific actions

     * for each error, such as inserting the message in a log file or

     * printing it to the console.</p>

     *

     * @param e The warning information encoded as an exception.

     * @exception org.xml.sax.SAXException Any SAX exception, possibly

     *            wrapping another exception.

     * @see org.xml.sax.ErrorHandler#warning

     * @see org.xml.sax.SAXParseException

     */

    public void error (SAXParseException e)

        throws SAXException

    {

        // no op

    }

    /**

     * Report a fatal XML parsing error.

     *

     * <p>The default implementation throws a SAXParseException.

     * Application writers may override this method in a subclass if

     * they need to take specific actions for each fatal error (such as

     * collecting all of the errors into a single report): in any case,

     * the application must stop all regular processing when this

     * method is invoked, since the document is no longer reliable, and

     * the parser may no longer report parsing events.</p>

     *

     * @param e The error information encoded as an exception.

     * @exception org.xml.sax.SAXException Any SAX exception, possibly

     *            wrapping another exception.

     * @see org.xml.sax.ErrorHandler#fatalError

     * @see org.xml.sax.SAXParseException

     */

    public void fatalError (SAXParseException e)

        throws SAXException

    {

        throw e;

    }

}

// end of HandlerBase.java