Source for org.xml.sax.DocumentHandler

   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 2004/12/23 22:38:42 mark 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