Home » xml-commons-external-1.4.01-src » org.xml » sax » [javadoc | source]

    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 226184 2005-04-08 10:53:24Z neeraj $
    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   public class HandlerBase
   46       implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler
   47   {
   48       
   49   
   50       ////////////////////////////////////////////////////////////////////
   51       // Default implementation of the EntityResolver interface.
   52       ////////////////////////////////////////////////////////////////////
   53       
   54       /**
   55        * Resolve an external entity.
   56        *
   57        * <p>Always return null, so that the parser will use the system
   58        * identifier provided in the XML document.  This method implements
   59        * the SAX default behaviour: application writers can override it
   60        * in a subclass to do special translations such as catalog lookups
   61        * or URI redirection.</p>
   62        *
   63        * @param publicId The public identifer, or null if none is
   64        *                 available.
   65        * @param systemId The system identifier provided in the XML 
   66        *                 document.
   67        * @return The new input source, or null to require the
   68        *         default behaviour.
   69        * @exception org.xml.sax.SAXException Any SAX exception, possibly
   70        *            wrapping another exception.
   71        * @see org.xml.sax.EntityResolver#resolveEntity
   72        */
   73       public InputSource resolveEntity (String publicId, String systemId)
   74   	throws SAXException
   75       {
   76   	return null;
   77       }
   78       
   79       
   80   
   81       ////////////////////////////////////////////////////////////////////
   82       // Default implementation of DTDHandler interface.
   83       ////////////////////////////////////////////////////////////////////
   84       
   85       
   86       /**
   87        * Receive notification of a notation declaration.
   88        *
   89        * <p>By default, do nothing.  Application writers may override this
   90        * method in a subclass if they wish to keep track of the notations
   91        * declared in a document.</p>
   92        *
   93        * @param name The notation name.
   94        * @param publicId The notation public identifier, or null if not
   95        *                 available.
   96        * @param systemId The notation system identifier.
   97        * @see org.xml.sax.DTDHandler#notationDecl
   98        */
   99       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

Home » xml-commons-external-1.4.01-src » org.xml » sax » [javadoc | source]