Source for org.xml.sax.ContentHandler

   1: // ContentHandler.java - handle main document content.
   2: // http://www.saxproject.org
   3: // Written by David Megginson
   4: // NO WARRANTY!  This class is in the public domain.
   5: // $Id: ContentHandler.java,v 1.1 2004/12/23 22:38:42 mark Exp $
   6: 
   7: package org.xml.sax;
   8: 
   9: 
  10: /**
  11:  * Receive notification of the logical content of a document.
  12:  *
  13:  * <blockquote>
  14:  * <em>This module, both source code and documentation, is in the
  15:  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  16:  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
  17:  * for further information.
  18:  * </blockquote>
  19:  *
  20:  * <p>This is the main interface that most SAX applications
  21:  * implement: if the application needs to be informed of basic parsing 
  22:  * events, it implements this interface and registers an instance with 
  23:  * the SAX parser using the {@link org.xml.sax.XMLReader#setContentHandler 
  24:  * setContentHandler} method.  The parser uses the instance to report 
  25:  * basic document-related events like the start and end of elements 
  26:  * and character data.</p>
  27:  *
  28:  * <p>The order of events in this interface is very important, and
  29:  * mirrors the order of information in the document itself.  For
  30:  * example, all of an element's content (character data, processing
  31:  * instructions, and/or subelements) will appear, in order, between
  32:  * the startElement event and the corresponding endElement event.</p>
  33:  *
  34:  * <p>This interface is similar to the now-deprecated SAX 1.0
  35:  * DocumentHandler interface, but it adds support for Namespaces
  36:  * and for reporting skipped entities (in non-validating XML
  37:  * processors).</p>
  38:  *
  39:  * <p>Implementors should note that there is also a 
  40:  * <code>ContentHandler</code> class in the <code>java.net</code>
  41:  * package; that means that it's probably a bad idea to do</p>
  42:  *
  43:  * <pre>import java.net.*;
  44:  * import org.xml.sax.*;
  45:  * </pre>
  46:  *
  47:  * <p>In fact, "import ...*" is usually a sign of sloppy programming
  48:  * anyway, so the user should consider this a feature rather than a
  49:  * bug.</p>
  50:  *
  51:  * @since SAX 2.0
  52:  * @author David Megginson
  53:  * @version 2.0.1+ (sax2r3pre1)
  54:  * @see org.xml.sax.XMLReader
  55:  * @see org.xml.sax.DTDHandler
  56:  * @see org.xml.sax.ErrorHandler
  57:  */
  58: public interface ContentHandler
  59: {
  60: 
  61:     /**
  62:      * Receive an object for locating the origin of SAX document events.
  63:      *
  64:      * <p>SAX parsers are strongly encouraged (though not absolutely
  65:      * required) to supply a locator: if it does so, it must supply
  66:      * the locator to the application by invoking this method before
  67:      * invoking any of the other methods in the ContentHandler
  68:      * interface.</p>
  69:      *
  70:      * <p>The locator allows the application to determine the end
  71:      * position of any document-related event, even if the parser is
  72:      * not reporting an error.  Typically, the application will
  73:      * use this information for reporting its own errors (such as
  74:      * character content that does not match an application's
  75:      * business rules).  The information returned by the locator
  76:      * is probably not sufficient for use with a search engine.</p>
  77:      *
  78:      * <p>Note that the locator will return correct information only
  79:      * during the invocation SAX event callbacks after
  80:      * {@link #startDocument startDocument} returns and before
  81:      * {@link #endDocument endDocument} is called.  The
  82:      * application should not attempt to use it at any other time.</p>
  83:      *
  84:      * @param locator an object that can return the location of
  85:      *                any SAX document event
  86:      * @see org.xml.sax.Locator
  87:      */
  88:     public void setDocumentLocator (Locator locator);
  89: 
  90: 
  91:     /**
  92:      * Receive notification of the beginning of a document.
  93:      *
  94:      * <p>The SAX parser will invoke this method only once, before any
  95:      * other event callbacks (except for {@link #setDocumentLocator 
  96:      * setDocumentLocator}).</p>
  97:      *
  98:      * @throws org.xml.sax.SAXException any SAX exception, possibly
  99:      *            wrapping another exception
 100:      * @see #endDocument
 101:      */
 102:     public void startDocument ()
 103:     throws SAXException;
 104: 
 105: 
 106:     /**
 107:      * Receive notification of the end of a document.
 108:      *
 109:      * <p><strong>There is an apparent contradiction between the
 110:      * documentation for this method and the documentation for {@link
 111:      * org.xml.sax.ErrorHandler#fatalError}.  Until this ambiguity is
 112:      * resolved in a future major release, clients should make no
 113:      * assumptions about whether endDocument() will or will not be
 114:      * invoked when the parser has reported a fatalError() or thrown
 115:      * an exception.</strong></p>
 116:      *
 117:      * <p>The SAX parser will invoke this method only once, and it will
 118:      * be the last method invoked during the parse.  The parser shall
 119:      * not invoke this method until it has either abandoned parsing
 120:      * (because of an unrecoverable error) or reached the end of
 121:      * input.</p>
 122:      *
 123:      * @throws org.xml.sax.SAXException any SAX exception, possibly
 124:      *            wrapping another exception
 125:      * @see #startDocument
 126:      */
 127:     public void endDocument()
 128:     throws SAXException;
 129: 
 130: 
 131:     /**
 132:      * Begin the scope of a prefix-URI Namespace mapping.
 133:      *
 134:      * <p>The information from this event is not necessary for
 135:      * normal Namespace processing: the SAX XML reader will 
 136:      * automatically replace prefixes for element and attribute
 137:      * names when the <code>http://xml.org/sax/features/namespaces</code>
 138:      * feature is <var>true</var> (the default).</p>
 139:      *
 140:      * <p>There are cases, however, when applications need to
 141:      * use prefixes in character data or in attribute values,
 142:      * where they cannot safely be expanded automatically; the
 143:      * start/endPrefixMapping event supplies the information
 144:      * to the application to expand prefixes in those contexts
 145:      * itself, if necessary.</p>
 146:      *
 147:      * <p>Note that start/endPrefixMapping events are not
 148:      * guaranteed to be properly nested relative to each other:
 149:      * all startPrefixMapping events will occur immediately before the
 150:      * corresponding {@link #startElement startElement} event, 
 151:      * and all {@link #endPrefixMapping endPrefixMapping}
 152:      * events will occur immediately after the corresponding
 153:      * {@link #endElement endElement} event,
 154:      * but their order is not otherwise 
 155:      * guaranteed.</p>
 156:      *
 157:      * <p>There should never be start/endPrefixMapping events for the
 158:      * "xml" prefix, since it is predeclared and immutable.</p>
 159:      *
 160:      * @param prefix the Namespace prefix being declared.
 161:      *    An empty string is used for the default element namespace,
 162:      *    which has no prefix.
 163:      * @param uri the Namespace URI the prefix is mapped to
 164:      * @throws org.xml.sax.SAXException the client may throw
 165:      *            an exception during processing
 166:      * @see #endPrefixMapping
 167:      * @see #startElement
 168:      */
 169:     public void startPrefixMapping (String prefix, String uri)
 170:     throws SAXException;
 171: 
 172: 
 173:     /**
 174:      * End the scope of a prefix-URI mapping.
 175:      *
 176:      * <p>See {@link #startPrefixMapping startPrefixMapping} for 
 177:      * details.  These events will always occur immediately after the
 178:      * corresponding {@link #endElement endElement} event, but the order of 
 179:      * {@link #endPrefixMapping endPrefixMapping} events is not otherwise
 180:      * guaranteed.</p>
 181:      *
 182:      * @param prefix the prefix that was being mapped.
 183:      *    This is the empty string when a default mapping scope ends.
 184:      * @throws org.xml.sax.SAXException the client may throw
 185:      *            an exception during processing
 186:      * @see #startPrefixMapping
 187:      * @see #endElement
 188:      */
 189:     public void endPrefixMapping (String prefix)
 190:     throws SAXException;
 191: 
 192: 
 193:     /**
 194:      * Receive notification of the beginning of an element.
 195:      *
 196:      * <p>The Parser will invoke this method at the beginning of every
 197:      * element in the XML document; there will be a corresponding
 198:      * {@link #endElement endElement} event for every startElement event
 199:      * (even when the element is empty). All of the element's content will be
 200:      * reported, in order, before the corresponding endElement
 201:      * event.</p>
 202:      *
 203:      * <p>This event allows up to three name components for each
 204:      * element:</p>
 205:      *
 206:      * <ol>
 207:      * <li>the Namespace URI;</li>
 208:      * <li>the local name; and</li>
 209:      * <li>the qualified (prefixed) name.</li>
 210:      * </ol>
 211:      *
 212:      * <p>Any or all of these may be provided, depending on the
 213:      * values of the <var>http://xml.org/sax/features/namespaces</var>
 214:      * and the <var>http://xml.org/sax/features/namespace-prefixes</var>
 215:      * properties:</p>
 216:      *
 217:      * <ul>
 218:      * <li>the Namespace URI and local name are required when 
 219:      * the namespaces property is <var>true</var> (the default), and are
 220:      * optional when the namespaces property is <var>false</var> (if one is
 221:      * specified, both must be);</li>
 222:      * <li>the qualified name is required when the namespace-prefixes property
 223:      * is <var>true</var>, and is optional when the namespace-prefixes property
 224:      * is <var>false</var> (the default).</li>
 225:      * </ul>
 226:      *
 227:      * <p>Note that the attribute list provided will contain only
 228:      * attributes with explicit values (specified or defaulted):
 229:      * #IMPLIED attributes will be omitted.  The attribute list
 230:      * will contain attributes used for Namespace declarations
 231:      * (xmlns* attributes) only if the
 232:      * <code>http://xml.org/sax/features/namespace-prefixes</code>
 233:      * property is true (it is false by default, and support for a 
 234:      * true value is optional).</p>
 235:      *
 236:      * <p>Like {@link #characters characters()}, attribute values may have
 237:      * characters that need more than one <code>char</code> value.  </p>
 238:      *
 239:      * @param uri the Namespace URI, or the empty string if the
 240:      *        element has no Namespace URI or if Namespace
 241:      *        processing is not being performed
 242:      * @param localName the local name (without prefix), or the
 243:      *        empty string if Namespace processing is not being
 244:      *        performed
 245:      * @param qName the qualified name (with prefix), or the
 246:      *        empty string if qualified names are not available
 247:      * @param atts the attributes attached to the element.  If
 248:      *        there are no attributes, it shall be an empty
 249:      *        Attributes object.  The value of this object after
 250:      *        startElement returns is undefined
 251:      * @throws org.xml.sax.SAXException any SAX exception, possibly
 252:      *            wrapping another exception
 253:      * @see #endElement
 254:      * @see org.xml.sax.Attributes
 255:      * @see org.xml.sax.helpers.AttributesImpl
 256:      */
 257:     public void startElement (String uri, String localName,
 258:                   String qName, Attributes atts)
 259:     throws SAXException;
 260: 
 261: 
 262:     /**
 263:      * Receive notification of the end of an element.
 264:      *
 265:      * <p>The SAX parser will invoke this method at the end of every
 266:      * element in the XML document; there will be a corresponding
 267:      * {@link #startElement startElement} event for every endElement 
 268:      * event (even when the element is empty).</p>
 269:      *
 270:      * <p>For information on the names, see startElement.</p>
 271:      *
 272:      * @param uri the Namespace URI, or the empty string if the
 273:      *        element has no Namespace URI or if Namespace
 274:      *        processing is not being performed
 275:      * @param localName the local name (without prefix), or the
 276:      *        empty string if Namespace processing is not being
 277:      *        performed
 278:      * @param qName the qualified XML name (with prefix), or the
 279:      *        empty string if qualified names are not available
 280:      * @throws org.xml.sax.SAXException any SAX exception, possibly
 281:      *            wrapping another exception
 282:      */
 283:     public void endElement (String uri, String localName,
 284:                 String qName)
 285:     throws SAXException;
 286: 
 287: 
 288:     /**
 289:      * Receive notification of character data.
 290:      *
 291:      * <p>The Parser will call this method to report each chunk of
 292:      * character data.  SAX parsers may return all contiguous character
 293:      * data in a single chunk, or they may split it into several
 294:      * chunks; however, all of the characters in any single event
 295:      * must come from the same external entity so that the Locator
 296:      * provides useful information.</p>
 297:      *
 298:      * <p>The application must not attempt to read from the array
 299:      * outside of the specified range.</p>
 300:      *
 301:      * <p>Individual characters may consist of more than one Java
 302:      * <code>char</code> value.  There are two important cases where this
 303:      * happens, because characters can't be represented in just sixteen bits.
 304:      * In one case, characters are represented in a <em>Surrogate Pair</em>,
 305:      * using two special Unicode values. Such characters are in the so-called
 306:      * "Astral Planes", with a code point above U+FFFF.  A second case involves
 307:      * composite characters, such as a base character combining with one or
 308:      * more accent characters. </p>
 309:      *
 310:      * <p> Your code should not assume that algorithms using
 311:      * <code>char</code>-at-a-time idioms will be working in character
 312:      * units; in some cases they will split characters.  This is relevant
 313:      * wherever XML permits arbitrary characters, such as attribute values,
 314:      * processing instruction data, and comments as well as in data reported
 315:      * from this method.  It's also generally relevant whenever Java code
 316:      * manipulates internationalized text; the issue isn't unique to XML.</p>
 317:      *
 318:      * <p>Note that some parsers will report whitespace in element
 319:      * content using the {@link #ignorableWhitespace ignorableWhitespace}
 320:      * method rather than this one (validating parsers <em>must</em> 
 321:      * do so).</p>
 322:      *
 323:      * @param ch the characters from the XML document
 324:      * @param start the start position in the array
 325:      * @param length the number of characters to read from the array
 326:      * @throws org.xml.sax.SAXException any SAX exception, possibly
 327:      *            wrapping another exception
 328:      * @see #ignorableWhitespace 
 329:      * @see org.xml.sax.Locator
 330:      */
 331:     public void characters (char ch[], int start, int length)
 332:     throws SAXException;
 333: 
 334: 
 335:     /**
 336:      * Receive notification of ignorable whitespace in element content.
 337:      *
 338:      * <p>Validating Parsers must use this method to report each chunk
 339:      * of whitespace in element content (see the W3C XML 1.0
 340:      * recommendation, section 2.10): non-validating parsers may also
 341:      * use this method if they are capable of parsing and using
 342:      * content models.</p>
 343:      *
 344:      * <p>SAX parsers may return all contiguous whitespace in a single
 345:      * chunk, or they may split it into several chunks; however, all of
 346:      * the characters in any single event must come from the same
 347:      * external entity, so that the Locator provides useful
 348:      * information.</p>
 349:      *
 350:      * <p>The application must not attempt to read from the array
 351:      * outside of the specified range.</p>
 352:      *
 353:      * @param ch the characters from the XML document
 354:      * @param start the start position in the array
 355:      * @param length the number of characters to read from the array
 356:      * @throws org.xml.sax.SAXException any SAX exception, possibly
 357:      *            wrapping another exception
 358:      * @see #characters
 359:      */
 360:     public void ignorableWhitespace (char ch[], int start, int length)
 361:     throws SAXException;
 362: 
 363: 
 364:     /**
 365:      * Receive notification of a processing instruction.
 366:      *
 367:      * <p>The Parser will invoke this method once for each processing
 368:      * instruction found: note that processing instructions may occur
 369:      * before or after the main document element.</p>
 370:      *
 371:      * <p>A SAX parser must never report an XML declaration (XML 1.0,
 372:      * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
 373:      * using this method.</p>
 374:      *
 375:      * <p>Like {@link #characters characters()}, processing instruction
 376:      * data may have characters that need more than one <code>char</code>
 377:      * value. </p>
 378:      *
 379:      * @param target the processing instruction target
 380:      * @param data the processing instruction data, or null if
 381:      *        none was supplied.  The data does not include any
 382:      *        whitespace separating it from the target
 383:      * @throws org.xml.sax.SAXException any SAX exception, possibly
 384:      *            wrapping another exception
 385:      */
 386:     public void processingInstruction (String target, String data)
 387:     throws SAXException;
 388: 
 389: 
 390:     /**
 391:      * Receive notification of a skipped entity.
 392:      * This is not called for entity references within markup constructs
 393:      * such as element start tags or markup declarations.  (The XML
 394:      * recommendation requires reporting skipped external entities.
 395:      * SAX also reports internal entity expansion/non-expansion, except
 396:      * within markup constructs.)
 397:      *
 398:      * <p>The Parser will invoke this method each time the entity is
 399:      * skipped.  Non-validating processors may skip entities if they
 400:      * have not seen the declarations (because, for example, the
 401:      * entity was declared in an external DTD subset).  All processors
 402:      * may skip external entities, depending on the values of the
 403:      * <code>http://xml.org/sax/features/external-general-entities</code>
 404:      * and the
 405:      * <code>http://xml.org/sax/features/external-parameter-entities</code>
 406:      * properties.</p>
 407:      *
 408:      * @param name the name of the skipped entity.  If it is a 
 409:      *        parameter entity, the name will begin with '%', and if
 410:      *        it is the external DTD subset, it will be the string
 411:      *        "[dtd]"
 412:      * @throws org.xml.sax.SAXException any SAX exception, possibly
 413:      *            wrapping another exception
 414:      */
 415:     public void skippedEntity (String name)
 416:     throws SAXException;
 417: }
 418: 
 419: // end of ContentHandler.java