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