libjava/external/sax/org/xml/sax/DocumentHandler.java

   1 // SAX document handler.
   2 // http://www.saxproject.org
   3 // No warranty; no copyright -- use this as you will.
   4 // $Id: DocumentHandler.java,v 1.1 2005/02/02 00:41:51 tromey Exp $
   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