1. // SAX document handler.

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

  3. // $Id: DocumentHandler.java,v 1.2 2001/08/01 06:43:17 tcng Exp $

  4. 

  5. package org.xml.sax;

  6. 

  7. /**

  8.  * Receive notification of general document events.

  9.  *

  10.  * <blockquote>

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

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

  13.  * </blockquote>

  14.  *

  15.  * <p>This was the main event-handling interface for SAX1; in

  16.  * SAX2, it has been replaced by {@link org.xml.sax.ContentHandler

  17.  * ContentHandler}, which provides Namespace support and reporting

  18.  * of skipped entities.  This interface is included in SAX2 only

  19.  * to support legacy SAX1 applications.</p>

  20.  *

  21.  * <p>The order of events in this interface is very important, and

  22.  * mirrors the order of information in the document itself.  For

  23.  * example, all of an element's content (character data, processing

  24.  * instructions, and/or subelements) will appear, in order, between

  25.  * the startElement event and the corresponding endElement event.</p>

  26.  *

  27.  * <p>Application writers who do not want to implement the entire

  28.  * interface can derive a class from HandlerBase, which implements

  29.  * the default functionality; parser writers can instantiate

  30.  * HandlerBase to obtain a default handler.  The application can find

  31.  * the location of any document event using the Locator interface

  32.  * supplied by the Parser through the setDocumentLocator method.</p>

  33.  *

  34.  * @deprecated This interface has been replaced by the SAX2

  35.  *             {@link org.xml.sax.ContentHandler ContentHandler}

  36.  *             interface, which includes Namespace support.

  37.  * @since SAX 1.0

  38.  * @author David Megginson, 

  39.  *         <a href="mailto:sax@megginson.com">sax@megginson.com</a>

  40.  * @version 2.0

  41.  * @see org.xml.sax.Parser#setDocumentHandler

  42.  * @see org.xml.sax.Locator

  43.  * @see org.xml.sax.HandlerBase

  44.  */

  45. public interface DocumentHandler {

  46.     

  47.     

  48.     /**

  49.      * Receive an object for locating the origin of SAX document events.

  50.      *

  51.      * <p>SAX parsers are strongly encouraged (though not absolutely

  52.      * required) to supply a locator: if it does so, it must supply

  53.      * the locator to the application by invoking this method before

  54.      * invoking any of the other methods in the DocumentHandler

  55.      * interface.</p>

  56.      *

  57.      * <p>The locator allows the application to determine the end

  58.      * position of any document-related event, even if the parser is

  59.      * not reporting an error.  Typically, the application will

  60.      * use this information for reporting its own errors (such as

  61.      * character content that does not match an application's

  62.      * business rules).  The information returned by the locator

  63.      * is probably not sufficient for use with a search engine.</p>

  64.      *

  65.      * <p>Note that the locator will return correct information only

  66.      * during the invocation of the events in this interface.  The

  67.      * application should not attempt to use it at any other time.</p>

  68.      *

  69.      * @param locator An object that can return the location of

  70.      *                any SAX document event.

  71.      * @see org.xml.sax.Locator

  72.      */

  73.     public abstract void setDocumentLocator (Locator locator);

  74.     

  75.     

  76.     /**

  77.      * Receive notification of the beginning of a document.

  78.      *

  79.      * <p>The SAX parser will invoke this method only once, before any

  80.      * other methods in this interface or in DTDHandler (except for

  81.      * setDocumentLocator).</p>

  82.      *

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

  84.      *            wrapping another exception.

  85.      */

  86.     public abstract void startDocument ()

  87. 	throws SAXException;

  88.     

  89.     

  90.     /**

  91.      * Receive notification of the end of a document.

  92.      *

  93.      * <p>The SAX parser will invoke this method only once, and it will

  94.      * be the last method invoked during the parse.  The parser shall

  95.      * not invoke this method until it has either abandoned parsing

  96.      * (because of an unrecoverable error) or reached the end of

  97.      * input.</p>

  98.      *

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

  100.      *            wrapping another exception.

  101.      */

  102.     public abstract void endDocument ()

  103. 	throws SAXException;

  104.     

  105.     

  106.     /**

  107.      * Receive notification of the beginning of an element.

  108.      *

  109.      * <p>The Parser will invoke this method at the beginning of every

  110.      * element in the XML document; there will be a corresponding

  111.      * endElement() event for every startElement() event (even when the

  112.      * element is empty). All of the element's content will be

  113.      * reported, in order, before the corresponding endElement()

  114.      * event.</p>

  115.      *

  116.      * <p>If the element name has a namespace prefix, the prefix will

  117.      * still be attached.  Note that the attribute list provided will

  118.      * contain only attributes with explicit values (specified or

  119.      * defaulted): #IMPLIED attributes will be omitted.</p>

  120.      *

  121.      * @param name The element type name.

  122.      * @param atts The attributes attached to the element, if any.

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

  124.      *            wrapping another exception.

  125.      * @see #endElement

  126.      * @see org.xml.sax.AttributeList 

  127.      */

  128.     public abstract void startElement (String name, AttributeList atts)

  129. 	throws SAXException;

  130.     

  131.     

  132.     /**

  133.      * Receive notification of the end of an element.

  134.      *

  135.      * <p>The SAX parser will invoke this method at the end of every

  136.      * element in the XML document; there will be a corresponding

  137.      * startElement() event for every endElement() event (even when the

  138.      * element is empty).</p>

  139.      *

  140.      * <p>If the element name has a namespace prefix, the prefix will

  141.      * still be attached to the name.</p>

  142.      *

  143.      * @param name The element type name

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

  145.      *            wrapping another exception.

  146.      */

  147.     public abstract void endElement (String name)

  148. 	throws SAXException;

  149.     

  150.     

  151.     /**

  152.      * Receive notification of character data.

  153.      *

  154.      * <p>The Parser will call this method to report each chunk of

  155.      * character data.  SAX parsers may return all contiguous character

  156.      * data in a single chunk, or they may split it into several

  157.      * chunks; however, all of the characters in any single event

  158.      * must come from the same external entity, so that the Locator

  159.      * provides useful information.</p>

  160.      *

  161.      * <p>The application must not attempt to read from the array

  162.      * outside of the specified range.</p>

  163.      *

  164.      * <p>Note that some parsers will report whitespace using the

  165.      * ignorableWhitespace() method rather than this one (validating

  166.      * parsers must do so).</p>

  167.      *

  168.      * @param ch The characters from the XML document.

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

  170.      * @param length The number of characters to read from the array.

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

  172.      *            wrapping another exception.

  173.      * @see #ignorableWhitespace 

  174.      * @see org.xml.sax.Locator

  175.      */

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

  177. 	throws SAXException;

  178.     

  179.     

  180.     /**

  181.      * Receive notification of ignorable whitespace in element content.

  182.      *

  183.      * <p>Validating Parsers must use this method to report each chunk

  184.      * of ignorable whitespace (see the W3C XML 1.0 recommendation,

  185.      * section 2.10): non-validating parsers may also use this method

  186.      * if they are capable of parsing and using content models.</p>

  187.      *

  188.      * <p>SAX parsers may return all contiguous whitespace in a single

  189.      * chunk, or they may split it into several chunks; however, all of

  190.      * the characters in any single event must come from the same

  191.      * external entity, so that the Locator provides useful

  192.      * information.</p>

  193.      *

  194.      * <p>The application must not attempt to read from the array

  195.      * outside of the specified range.</p>

  196.      *

  197.      * @param ch The characters from the XML document.

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

  199.      * @param length The number of characters to read from the array.

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

  201.      *            wrapping another exception.

  202.      * @see #characters

  203.      */

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

  205. 	throws SAXException;

  206.     

  207.     

  208.     /**

  209.      * Receive notification of a processing instruction.

  210.      *

  211.      * <p>The Parser will invoke this method once for each processing

  212.      * instruction found: note that processing instructions may occur

  213.      * before or after the main document element.</p>

  214.      *

  215.      * <p>A SAX parser should never report an XML declaration (XML 1.0,

  216.      * section 2.8) or a text declaration (XML 1.0, section 4.3.1)

  217.      * using this method.</p>

  218.      *

  219.      * @param target The processing instruction target.

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

  221.      *        none was supplied.

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

  223.      *            wrapping another exception.

  224.      */

  225.     public abstract void processingInstruction (String target, String data)

  226. 	throws SAXException;

  227.     

  228. }

  229. 

  230. // end of DocumentHandler.java