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

    1   // SAX document handler.
    2   // http://www.saxproject.org
    3   // No warranty; no copyright -- use this as you will.
    4   // $Id: DocumentHandler.java 226184 2005-04-08 10:53:24Z neeraj $
    5   
    6   package org.xml.sax;
    7   
    8   /**
    9    * Receive notification of general document events.
   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 was the main event-handling interface for SAX1; in
   19    * SAX2, it has been replaced by {@link org.xml.sax.ContentHandler
   20    * ContentHandler}, which provides Namespace support and reporting
   21    * of skipped entities.  This interface is included in SAX2 only
   22    * to support legacy SAX1 applications.</p>
   23    *
   24    * <p>The order of events in this interface is very important, and
   25    * mirrors the order of information in the document itself.  For
   26    * example, all of an element's content (character data, processing
   27    * instructions, and/or subelements) will appear, in order, between
   28    * the startElement event and the corresponding endElement event.</p>
   29    *
   30    * <p>Application writers who do not want to implement the entire
   31    * interface can derive a class from HandlerBase, which implements
   32    * the default functionality; parser writers can instantiate
   33    * HandlerBase to obtain a default handler.  The application can find
   34    * the location of any document event using the Locator interface
   35    * supplied by the Parser through the setDocumentLocator method.</p>
   36    *
   37    * @deprecated This interface has been replaced by the SAX2
   38    *             {@link org.xml.sax.ContentHandler ContentHandler}
   39    *             interface, which includes Namespace support.
   40    * @since SAX 1.0
   41    * @author David Megginson
   42    * @version 2.0.1 (sax2r2)
   43    * @see org.xml.sax.Parser#setDocumentHandler
   44    * @see org.xml.sax.Locator
   45    * @see org.xml.sax.HandlerBase
   46    */
   47   public interface DocumentHandler {
   48       
   49       
   50       /**
   51        * Receive an object for locating the origin of SAX document events.
   52        *
   53        * <p>SAX parsers are strongly encouraged (though not absolutely
   54        * required) to supply a locator: if it does so, it must supply
   55        * the locator to the application by invoking this method before
   56        * invoking any of the other methods in the DocumentHandler
   57        * interface.</p>
   58        *
   59        * <p>The locator allows the application to determine the end
   60        * position of any document-related event, even if the parser is
   61        * not reporting an error.  Typically, the application will
   62        * use this information for reporting its own errors (such as
   63        * character content that does not match an application's
   64        * business rules).  The information returned by the locator
   65        * is probably not sufficient for use with a search engine.</p>
   66        *
   67        * <p>Note that the locator will return correct information only
   68        * during the invocation of the events in this interface.  The
   69        * application should not attempt to use it at any other time.</p>
   70        *
   71        * @param locator An object that can return the location of
   72        *                any SAX document event.
   73        * @see org.xml.sax.Locator
   74        */
   75       public abstract void setDocumentLocator (Locator locator);
   76       
   77       
   78       /**
   79        * Receive notification of the beginning of a document.
   80        *
   81        * <p>The SAX parser will invoke this method only once, before any
   82        * other methods in this interface or in DTDHandler (except for
   83        * setDocumentLocator).</p>
   84        *
   85        * @exception org.xml.sax.SAXException Any SAX exception, possibly
   86        *            wrapping another exception.
   87        */
   88       public abstract void startDocument ()
   89   	throws SAXException;
   90       
   91       
   92       /**
   93        * Receive notification of the end of a document.
   94        *
   95        * <p>The SAX parser will invoke this method only once, and it will
   96        * be the last method invoked during the parse.  The parser shall
   97        * not invoke this method until it has either abandoned parsing
   98        * (because of an unrecoverable error) or reached the end of
   99        * input.</p>
  100        *
  101        * @exception org.xml.sax.SAXException Any SAX exception, possibly
  102        *            wrapping another exception.
  103        */
  104       public abstract void endDocument ()
  105   	throws SAXException;
  106       
  107       
  108       /**
  109        * Receive notification of the beginning of an element.
  110        *
  111        * <p>The Parser will invoke this method at the beginning of every
  112        * element in the XML document; there will be a corresponding
  113        * endElement() event for every startElement() event (even when the
  114        * element is empty). All of the element's content will be
  115        * reported, in order, before the corresponding endElement()
  116        * event.</p>
  117        *
  118        * <p>If the element name has a namespace prefix, the prefix will
  119        * still be attached.  Note that the attribute list provided will
  120        * contain only attributes with explicit values (specified or
  121        * defaulted): #IMPLIED attributes will be omitted.</p>
  122        *
  123        * @param name The element type name.
  124        * @param atts The attributes attached to the element, if any.
  125        * @exception org.xml.sax.SAXException Any SAX exception, possibly
  126        *            wrapping another exception.
  127        * @see #endElement
  128        * @see org.xml.sax.AttributeList 
  129        */
  130       public abstract void startElement (String name, AttributeList atts)
  131   	throws SAXException;
  132       
  133       
  134       /**
  135        * Receive notification of the end of an element.
  136        *
  137        * <p>The SAX parser will invoke this method at the end of every
  138        * element in the XML document; there will be a corresponding
  139        * startElement() event for every endElement() event (even when the
  140        * element is empty).</p>
  141        *
  142        * <p>If the element name has a namespace prefix, the prefix will
  143        * still be attached to the name.</p>
  144        *
  145        * @param name The element type name
  146        * @exception org.xml.sax.SAXException Any SAX exception, possibly
  147        *            wrapping another exception.
  148        */
  149       public abstract void endElement (String name)
  150   	throws SAXException;
  151       
  152       
  153       /**
  154        * Receive notification of character data.
  155        *
  156        * <p>The Parser will call this method to report each chunk of
  157        * character data.  SAX parsers may return all contiguous character
  158        * data in a single chunk, or they may split it into several
  159        * chunks; however, all of the characters in any single event
  160        * must come from the same external entity, so that the Locator
  161        * provides useful information.</p>
  162        *
  163        * <p>The application must not attempt to read from the array
  164        * outside of the specified range.</p>
  165        *
  166        * <p>Note that some parsers will report whitespace using the
  167        * ignorableWhitespace() method rather than this one (validating
  168        * parsers must do so).</p>
  169        *
  170        * @param ch The characters from the XML document.
  171        * @param start The start position in the array.
  172        * @param length The number of characters to read from the array.
  173        * @exception org.xml.sax.SAXException Any SAX exception, possibly
  174        *            wrapping another exception.
  175        * @see #ignorableWhitespace 
  176        * @see org.xml.sax.Locator
  177        */
  178       public abstract void characters (char ch[], int start, int length)
  179   	throws SAXException;
  180       
  181       
  182       /**
  183        * Receive notification of ignorable whitespace in element content.
  184        *
  185        * <p>Validating Parsers must use this method to report each chunk
  186        * of ignorable whitespace (see the W3C XML 1.0 recommendation,
  187        * section 2.10): non-validating parsers may also use this method
  188        * if they are capable of parsing and using content models.</p>
  189        *
  190        * <p>SAX parsers may return all contiguous whitespace in a single
  191        * chunk, or they may split it into several chunks; however, all of
  192        * the characters in any single event must come from the same
  193        * external entity, so that the Locator provides useful
  194        * information.</p>
  195        *
  196        * <p>The application must not attempt to read from the array
  197        * outside of the specified range.</p>
  198        *
  199        * @param ch The characters from the XML document.
  200        * @param start The start position in the array.
  201        * @param length The number of characters to read from the array.
  202        * @exception org.xml.sax.SAXException Any SAX exception, possibly
  203        *            wrapping another exception.
  204        * @see #characters
  205        */
  206       public abstract void ignorableWhitespace (char ch[], int start, int length)
  207   	throws SAXException;
  208       
  209       
  210       /**
  211        * Receive notification of a processing instruction.
  212        *
  213        * <p>The Parser will invoke this method once for each processing
  214        * instruction found: note that processing instructions may occur
  215        * before or after the main document element.</p>
  216        *
  217        * <p>A SAX parser should never report an XML declaration (XML 1.0,
  218        * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
  219        * using this method.</p>
  220        *
  221        * @param target The processing instruction target.
  222        * @param data The processing instruction data, or null if
  223        *        none was supplied.
  224        * @exception org.xml.sax.SAXException Any SAX exception, possibly
  225        *            wrapping another exception.
  226        */
  227       public abstract void processingInstruction (String target, String data)
  228   	throws SAXException;
  229       
  230   }
  231   
  232   // end of DocumentHandler.java

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