+++ /dev/null
-// ContentHandler.java - handle main document content.\r
-// Written by David Megginson, sax@megginson.com\r
-// NO WARRANTY! This class is in the public domain.\r
-\r
-// $Id: ContentHandler.java,v 1.1 2000/10/02 02:43:16 sboag Exp $\r
-\r
-package org.xml.sax;\r
-\r
-\r
-/**\r
- * Receive notification of the logical content of a document.\r
- *\r
- * <blockquote>\r
- * <em>This module, both source code and documentation, is in the\r
- * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>\r
- * </blockquote>\r
- *\r
- * <p>This is the main interface that most SAX applications\r
- * implement: if the application needs to be informed of basic parsing \r
- * events, it implements this interface and registers an instance with \r
- * the SAX parser using the {@link org.xml.sax.XMLReader#setContentHandler \r
- * setContentHandler} method. The parser uses the instance to report \r
- * basic document-related events like the start and end of elements \r
- * and character data.</p>\r
- *\r
- * <p>The order of events in this interface is very important, and\r
- * mirrors the order of information in the document itself. For\r
- * example, all of an element's content (character data, processing\r
- * instructions, and/or subelements) will appear, in order, between\r
- * the startElement event and the corresponding endElement event.</p>\r
- *\r
- * <p>This interface is similar to the now-deprecated SAX 1.0\r
- * DocumentHandler interface, but it adds support for Namespaces\r
- * and for reporting skipped entities (in non-validating XML\r
- * processors).</p>\r
- *\r
- * <p>Implementors should note that there is also a Java class\r
- * {@link java.net.ContentHandler ContentHandler} in the java.net\r
- * package; that means that it's probably a bad idea to do</p>\r
- *\r
- * <blockquote>\r
- * import java.net.*;\r
- * import org.xml.sax.*;\r
- * </blockquote>\r
- *\r
- * <p>In fact, "import ...*" is usually a sign of sloppy programming\r
- * anyway, so the user should consider this a feature rather than a\r
- * bug.</p>\r
- *\r
- * @since SAX 2.0\r
- * @author David Megginson, \r
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>\r
- * @version 2.0\r
- * @see org.xml.sax.XMLReader\r
- * @see org.xml.sax.DTDHandler\r
- * @see org.xml.sax.ErrorHandler\r
- */\r
-public interface ContentHandler\r
-{\r
-\r
- /**\r
- * Receive an object for locating the origin of SAX document events.\r
- *\r
- * <p>SAX parsers are strongly encouraged (though not absolutely\r
- * required) to supply a locator: if it does so, it must supply\r
- * the locator to the application by invoking this method before\r
- * invoking any of the other methods in the ContentHandler\r
- * interface.</p>\r
- *\r
- * <p>The locator allows the application to determine the end\r
- * position of any document-related event, even if the parser is\r
- * not reporting an error. Typically, the application will\r
- * use this information for reporting its own errors (such as\r
- * character content that does not match an application's\r
- * business rules). The information returned by the locator\r
- * is probably not sufficient for use with a search engine.</p>\r
- *\r
- * <p>Note that the locator will return correct information only\r
- * during the invocation of the events in this interface. The\r
- * application should not attempt to use it at any other time.</p>\r
- *\r
- * @param locator An object that can return the location of\r
- * any SAX document event.\r
- * @see org.xml.sax.Locator\r
- */\r
- public void setDocumentLocator (Locator locator);\r
-\r
-\r
- /**\r
- * Receive notification of the beginning of a document.\r
- *\r
- * <p>The SAX parser will invoke this method only once, before any\r
- * other methods in this interface or in {@link org.xml.sax.DTDHandler\r
- * DTDHandler} (except for {@link #setDocumentLocator \r
- * setDocumentLocator}).</p>\r
- *\r
- * @exception org.xml.sax.SAXException Any SAX exception, possibly\r
- * wrapping another exception.\r
- * @see #endDocument\r
- */\r
- public void startDocument ()\r
- throws SAXException;\r
-\r
-\r
- /**\r
- * Receive notification of the end of a document.\r
- *\r
- * <p>The SAX parser will invoke this method only once, and it will\r
- * be the last method invoked during the parse. The parser shall\r
- * not invoke this method until it has either abandoned parsing\r
- * (because of an unrecoverable error) or reached the end of\r
- * input.</p>\r
- *\r
- * @exception org.xml.sax.SAXException Any SAX exception, possibly\r
- * wrapping another exception.\r
- * @see #startDocument\r
- */\r
- public void endDocument()\r
- throws SAXException;\r
-\r
-\r
- /**\r
- * Begin the scope of a prefix-URI Namespace mapping.\r
- *\r
- * <p>The information from this event is not necessary for\r
- * normal Namespace processing: the SAX XML reader will \r
- * automatically replace prefixes for element and attribute\r
- * names when the <code>http://xml.org/sax/features/namespaces</code>\r
- * feature is <var>true</var> (the default).</p>\r
- *\r
- * <p>There are cases, however, when applications need to\r
- * use prefixes in character data or in attribute values,\r
- * where they cannot safely be expanded automatically; the\r
- * start/endPrefixMapping event supplies the information\r
- * to the application to expand prefixes in those contexts\r
- * itself, if necessary.</p>\r
- *\r
- * <p>Note that start/endPrefixMapping events are not\r
- * guaranteed to be properly nested relative to each-other:\r
- * all startPrefixMapping events will occur before the\r
- * corresponding {@link #startElement startElement} event, \r
- * and all {@link #endPrefixMapping endPrefixMapping}\r
- * events will occur after the corresponding {@link #endElement\r
- * endElement} event, but their order is not otherwise \r
- * guaranteed.</p>\r
- *\r
- * <p>There should never be start/endPrefixMapping events for the\r
- * "xml" prefix, since it is predeclared and immutable.</p>\r
- *\r
- * @param prefix The Namespace prefix being declared.\r
- * @param uri The Namespace URI the prefix is mapped to.\r
- * @exception org.xml.sax.SAXException The client may throw\r
- * an exception during processing.\r
- * @see #endPrefixMapping\r
- * @see #startElement\r
- */\r
- public void startPrefixMapping (String prefix, String uri)\r
- throws SAXException;\r
-\r
-\r
- /**\r
- * End the scope of a prefix-URI mapping.\r
- *\r
- * <p>See {@link #startPrefixMapping startPrefixMapping} for \r
- * details. This event will always occur after the corresponding \r
- * {@link #endElement endElement} event, but the order of \r
- * {@link #endPrefixMapping endPrefixMapping} events is not otherwise\r
- * guaranteed.</p>\r
- *\r
- * @param prefix The prefix that was being mapping.\r
- * @exception org.xml.sax.SAXException The client may throw\r
- * an exception during processing.\r
- * @see #startPrefixMapping\r
- * @see #endElement\r
- */\r
- public void endPrefixMapping (String prefix)\r
- throws SAXException;\r
-\r
-\r
- /**\r
- * Receive notification of the beginning of an element.\r
- *\r
- * <p>The Parser will invoke this method at the beginning of every\r
- * element in the XML document; there will be a corresponding\r
- * {@link #endElement endElement} event for every startElement event\r
- * (even when the element is empty). All of the element's content will be\r
- * reported, in order, before the corresponding endElement\r
- * event.</p>\r
- *\r
- * <p>This event allows up to three name components for each\r
- * element:</p>\r
- *\r
- * <ol>\r
- * <li>the Namespace URI;</li>\r
- * <li>the local name; and</li>\r
- * <li>the qualified (prefixed) name.</li>\r
- * </ol>\r
- *\r
- * <p>Any or all of these may be provided, depending on the\r
- * values of the <var>http://xml.org/sax/features/namespaces</var>\r
- * and the <var>http://xml.org/sax/features/namespace-prefixes</var>\r
- * properties:</p>\r
- *\r
- * <ul>\r
- * <li>the Namespace URI and local name are required when \r
- * the namespaces property is <var>true</var> (the default), and are\r
- * optional when the namespaces property is <var>false</var> (if one is\r
- * specified, both must be);</li>\r
- * <li>the qualified name is required when the namespace-prefixes property\r
- * is <var>true</var>, and is optional when the namespace-prefixes property\r
- * is <var>false</var> (the default).</li>\r
- * </ul>\r
- *\r
- * <p>Note that the attribute list provided will contain only\r
- * attributes with explicit values (specified or defaulted):\r
- * #IMPLIED attributes will be omitted. The attribute list\r
- * will contain attributes used for Namespace declarations\r
- * (xmlns* attributes) only if the\r
- * <code>http://xml.org/sax/features/namespace-prefixes</code>\r
- * property is true (it is false by default, and support for a \r
- * true value is optional).</p>\r
- *\r
- * @param uri The Namespace URI, or the empty string if the\r
- * element has no Namespace URI or if Namespace\r
- * processing is not being performed.\r
- * @param localName The local name (without prefix), or the\r
- * empty string if Namespace processing is not being\r
- * performed.\r
- * @param qName The qualified name (with prefix), or the\r
- * empty string if qualified names are not available.\r
- * @param atts The attributes attached to the element. If\r
- * there are no attributes, it shall be an empty\r
- * Attributes object.\r
- * @exception org.xml.sax.SAXException Any SAX exception, possibly\r
- * wrapping another exception.\r
- * @see #endElement\r
- * @see org.xml.sax.Attributes\r
- */\r
- public void startElement (String namespaceURI, String localName,\r
- String qName, Attributes atts)\r
- throws SAXException;\r
-\r
-\r
- /**\r
- * Receive notification of the end of an element.\r
- *\r
- * <p>The SAX parser will invoke this method at the end of every\r
- * element in the XML document; there will be a corresponding\r
- * {@link #startElement startElement} event for every endElement \r
- * event (even when the element is empty).</p>\r
- *\r
- * <p>For information on the names, see startElement.</p>\r
- *\r
- * @param uri The Namespace URI, or the empty string if the\r
- * element has no Namespace URI or if Namespace\r
- * processing is not being performed.\r
- * @param localName The local name (without prefix), or the\r
- * empty string if Namespace processing is not being\r
- * performed.\r
- * @param qName The qualified XML 1.0 name (with prefix), or the\r
- * empty string if qualified names are not available.\r
- * @exception org.xml.sax.SAXException Any SAX exception, possibly\r
- * wrapping another exception.\r
- */\r
- public void endElement (String namespaceURI, String localName,\r
- String qName)\r
- throws SAXException;\r
-\r
-\r
- /**\r
- * Receive notification of character data.\r
- *\r
- * <p>The Parser will call this method to report each chunk of\r
- * character data. SAX parsers may return all contiguous character\r
- * data in a single chunk, or they may split it into several\r
- * chunks; however, all of the characters in any single event\r
- * must come from the same external entity so that the Locator\r
- * provides useful information.</p>\r
- *\r
- * <p>The application must not attempt to read from the array\r
- * outside of the specified range.</p>\r
- *\r
- * <p>Note that some parsers will report whitespace in element\r
- * content using the {@link #ignorableWhitespace ignorableWhitespace}\r
- * method rather than this one (validating parsers <em>must</em> \r
- * do so).</p>\r
- *\r
- * @param ch The characters from the XML document.\r
- * @param start The start position in the array.\r
- * @param length The number of characters to read from the array.\r
- * @exception org.xml.sax.SAXException Any SAX exception, possibly\r
- * wrapping another exception.\r
- * @see #ignorableWhitespace \r
- * @see org.xml.sax.Locator\r
- */\r
- public void characters (char ch[], int start, int length)\r
- throws SAXException;\r
-\r
-\r
- /**\r
- * Receive notification of ignorable whitespace in element content.\r
- *\r
- * <p>Validating Parsers must use this method to report each chunk\r
- * of whitespace in element content (see the W3C XML 1.0 recommendation,\r
- * section 2.10): non-validating parsers may also use this method\r
- * if they are capable of parsing and using content models.</p>\r
- *\r
- * <p>SAX parsers may return all contiguous whitespace in a single\r
- * chunk, or they may split it into several chunks; however, all of\r
- * the characters in any single event must come from the same\r
- * external entity, so that the Locator provides useful\r
- * information.</p>\r
- *\r
- * <p>The application must not attempt to read from the array\r
- * outside of the specified range.</p>\r
- *\r
- * @param ch The characters from the XML document.\r
- * @param start The start position in the array.\r
- * @param length The number of characters to read from the array.\r
- * @exception org.xml.sax.SAXException Any SAX exception, possibly\r
- * wrapping another exception.\r
- * @see #characters\r
- */\r
- public void ignorableWhitespace (char ch[], int start, int length)\r
- throws SAXException;\r
-\r
-\r
- /**\r
- * Receive notification of a processing instruction.\r
- *\r
- * <p>The Parser will invoke this method once for each processing\r
- * instruction found: note that processing instructions may occur\r
- * before or after the main document element.</p>\r
- *\r
- * <p>A SAX parser must never report an XML declaration (XML 1.0,\r
- * section 2.8) or a text declaration (XML 1.0, section 4.3.1)\r
- * using this method.</p>\r
- *\r
- * @param target The processing instruction target.\r
- * @param data The processing instruction data, or null if\r
- * none was supplied. The data does not include any\r
- * whitespace separating it from the target.\r
- * @exception org.xml.sax.SAXException Any SAX exception, possibly\r
- * wrapping another exception.\r
- */\r
- public void processingInstruction (String target, String data)\r
- throws SAXException;\r
-\r
-\r
- /**\r
- * Receive notification of a skipped entity.\r
- *\r
- * <p>The Parser will invoke this method once for each entity\r
- * skipped. Non-validating processors may skip entities if they\r
- * have not seen the declarations (because, for example, the\r
- * entity was declared in an external DTD subset). All processors\r
- * may skip external entities, depending on the values of the\r
- * <code>http://xml.org/sax/features/external-general-entities</code>\r
- * and the\r
- * <code>http://xml.org/sax/features/external-parameter-entities</code>\r
- * properties.</p>\r
- *\r
- * @param name The name of the skipped entity. If it is a \r
- * parameter entity, the name will begin with '%', and if\r
- * it is the external DTD subset, it will be the string\r
- * "[dtd]".\r
- * @exception org.xml.sax.SAXException Any SAX exception, possibly\r
- * wrapping another exception.\r
- */\r
- public void skippedEntity (String name)\r
- throws SAXException;\r
-}\r
-\r
-// end of ContentHandler.java\r
projects / msp430-gcc.git / blobdiff