+++ /dev/null
-// XMLReader.java - read an XML document.\r
-// Written by David Megginson, sax@megginson.com\r
-// NO WARRANTY! This class is in the Public Domain.\r
-\r
-// $Id: XMLReader.java,v 1.1 2000/10/02 02:43:17 sboag Exp $\r
-\r
-package org.xml.sax;\r
-\r
-import java.io.IOException;\r
-\r
-\r
-/**\r
- * Interface for reading an XML document using callbacks.\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><strong>Note:</strong> despite its name, this interface does \r
- * <em>not</em> extend the standard Java {@link java.io.Reader Reader} \r
- * interface, because reading XML is a fundamentally different activity \r
- * than reading character data.</p>\r
- *\r
- * <p>XMLReader is the interface that an XML parser's SAX2 driver must\r
- * implement. This interface allows an application to set and\r
- * query features and properties in the parser, to register\r
- * event handlers for document processing, and to initiate\r
- * a document parse.</p>\r
- *\r
- * <p>All SAX interfaces are assumed to be synchronous: the\r
- * {@link #parse parse} methods must not return until parsing\r
- * is complete, and readers must wait for an event-handler callback\r
- * to return before reporting the next event.</p>\r
- *\r
- * <p>This interface replaces the (now deprecated) SAX 1.0 {@link\r
- * org.xml.sax.Parser Parser} interface. The XMLReader interface\r
- * contains two important enhancements over the old Parser\r
- * interface:</p>\r
- *\r
- * <ol>\r
- * <li>it adds a standard way to query and set features and \r
- * properties; and</li>\r
- * <li>it adds Namespace support, which is required for many\r
- * higher-level XML standards.</li>\r
- * </ol>\r
- *\r
- * <p>There are adapters available to convert a SAX1 Parser to\r
- * a SAX2 XMLReader and vice-versa.</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.XMLFilter\r
- * @see org.xml.sax.helpers.ParserAdapter\r
- * @see org.xml.sax.helpers.XMLReaderAdapter \r
- */\r
-public interface XMLReader\r
-{\r
-\r
-\f\r
- ////////////////////////////////////////////////////////////////////\r
- // Configuration.\r
- ////////////////////////////////////////////////////////////////////\r
-\r
-\r
- /**\r
- * Look up the value of a feature.\r
- *\r
- * <p>The feature name is any fully-qualified URI. It is\r
- * possible for an XMLReader to recognize a feature name but\r
- * to be unable to return its value; this is especially true\r
- * in the case of an adapter for a SAX1 Parser, which has\r
- * no way of knowing whether the underlying parser is\r
- * performing validation or expanding external entities.</p>\r
- *\r
- * <p>All XMLReaders are required to recognize the\r
- * http://xml.org/sax/features/namespaces and the\r
- * http://xml.org/sax/features/namespace-prefixes feature names.</p>\r
- *\r
- * <p>Some feature values may be available only in specific\r
- * contexts, such as before, during, or after a parse.</p>\r
- *\r
- * <p>Typical usage is something like this:</p>\r
- *\r
- * <pre>\r
- * XMLReader r = new MySAXDriver();\r
- *\r
- * // try to activate validation\r
- * try {\r
- * r.setFeature("http://xml.org/sax/features/validation", true);\r
- * } catch (SAXException e) {\r
- * System.err.println("Cannot activate validation."); \r
- * }\r
- *\r
- * // register event handlers\r
- * r.setContentHandler(new MyContentHandler());\r
- * r.setErrorHandler(new MyErrorHandler());\r
- *\r
- * // parse the first document\r
- * try {\r
- * r.parse("http://www.foo.com/mydoc.xml");\r
- * } catch (IOException e) {\r
- * System.err.println("I/O exception reading XML document");\r
- * } catch (SAXException e) {\r
- * System.err.println("XML exception reading document.");\r
- * }\r
- * </pre>\r
- *\r
- * <p>Implementors are free (and encouraged) to invent their own features,\r
- * using names built on their own URIs.</p>\r
- *\r
- * @param name The feature name, which is a fully-qualified URI.\r
- * @return The current state of the feature (true or false).\r
- * @exception org.xml.sax.SAXNotRecognizedException When the\r
- * XMLReader does not recognize the feature name.\r
- * @exception org.xml.sax.SAXNotSupportedException When the\r
- * XMLReader recognizes the feature name but \r
- * cannot determine its value at this time.\r
- * @see #setFeature\r
- */\r
- public boolean getFeature (String name)\r
- throws SAXNotRecognizedException, SAXNotSupportedException;\r
-\r
-\r
- /**\r
- * Set the state of a feature.\r
- *\r
- * <p>The feature name is any fully-qualified URI. It is\r
- * possible for an XMLReader to recognize a feature name but\r
- * to be unable to set its value; this is especially true\r
- * in the case of an adapter for a SAX1 {@link org.xml.sax.Parser Parser},\r
- * which has no way of affecting whether the underlying parser is\r
- * validating, for example.</p>\r
- *\r
- * <p>All XMLReaders are required to support setting\r
- * http://xml.org/sax/features/namespaces to true and\r
- * http://xml.org/sax/features/namespace-prefixes to false.</p>\r
- *\r
- * <p>Some feature values may be immutable or mutable only \r
- * in specific contexts, such as before, during, or after \r
- * a parse.</p>\r
- *\r
- * @param name The feature name, which is a fully-qualified URI.\r
- * @param state The requested state of the feature (true or false).\r
- * @exception org.xml.sax.SAXNotRecognizedException When the\r
- * XMLReader does not recognize the feature name.\r
- * @exception org.xml.sax.SAXNotSupportedException When the\r
- * XMLReader recognizes the feature name but \r
- * cannot set the requested value.\r
- * @see #getFeature\r
- */\r
- public void setFeature (String name, boolean value)\r
- throws SAXNotRecognizedException, SAXNotSupportedException;\r
-\r
-\r
- /**\r
- * Look up the value of a property.\r
- *\r
- * <p>The property name is any fully-qualified URI. It is\r
- * possible for an XMLReader to recognize a property name but\r
- * to be unable to return its state; this is especially true\r
- * in the case of an adapter for a SAX1 {@link org.xml.sax.Parser\r
- * Parser}.</p>\r
- *\r
- * <p>XMLReaders are not required to recognize any specific\r
- * property names, though an initial core set is documented for\r
- * SAX2.</p>\r
- *\r
- * <p>Some property values may be available only in specific\r
- * contexts, such as before, during, or after a parse.</p>\r
- *\r
- * <p>Implementors are free (and encouraged) to invent their own properties,\r
- * using names built on their own URIs.</p>\r
- *\r
- * @param name The property name, which is a fully-qualified URI.\r
- * @return The current value of the property.\r
- * @exception org.xml.sax.SAXNotRecognizedException When the\r
- * XMLReader does not recognize the property name.\r
- * @exception org.xml.sax.SAXNotSupportedException When the\r
- * XMLReader recognizes the property name but \r
- * cannot determine its value at this time.\r
- * @see #setProperty\r
- */\r
- public Object getProperty (String name)\r
- throws SAXNotRecognizedException, SAXNotSupportedException;\r
-\r
-\r
- /**\r
- * Set the value of a property.\r
- *\r
- * <p>The property name is any fully-qualified URI. It is\r
- * possible for an XMLReader to recognize a property name but\r
- * to be unable to set its value; this is especially true\r
- * in the case of an adapter for a SAX1 {@link org.xml.sax.Parser\r
- * Parser}.</p>\r
- *\r
- * <p>XMLReaders are not required to recognize setting\r
- * any specific property names, though a core set is provided with \r
- * SAX2.</p>\r
- *\r
- * <p>Some property values may be immutable or mutable only \r
- * in specific contexts, such as before, during, or after \r
- * a parse.</p>\r
- *\r
- * <p>This method is also the standard mechanism for setting\r
- * extended handlers.</p>\r
- *\r
- * @param name The property name, which is a fully-qualified URI.\r
- * @param state The requested value for the property.\r
- * @exception org.xml.sax.SAXNotRecognizedException When the\r
- * XMLReader does not recognize the property name.\r
- * @exception org.xml.sax.SAXNotSupportedException When the\r
- * XMLReader recognizes the property name but \r
- * cannot set the requested value.\r
- */\r
- public void setProperty (String name, Object value)\r
- throws SAXNotRecognizedException, SAXNotSupportedException;\r
-\r
-\r
-\f\r
- ////////////////////////////////////////////////////////////////////\r
- // Event handlers.\r
- ////////////////////////////////////////////////////////////////////\r
-\r
-\r
- /**\r
- * Allow an application to register an entity resolver.\r
- *\r
- * <p>If the application does not register an entity resolver,\r
- * the XMLReader will perform its own default resolution.</p>\r
- *\r
- * <p>Applications may register a new or different resolver in the\r
- * middle of a parse, and the SAX parser must begin using the new\r
- * resolver immediately.</p>\r
- *\r
- * @param resolver The entity resolver.\r
- * @exception java.lang.NullPointerException If the resolver \r
- * argument is null.\r
- * @see #getEntityResolver\r
- */\r
- public void setEntityResolver (EntityResolver resolver);\r
-\r
-\r
- /**\r
- * Return the current entity resolver.\r
- *\r
- * @return The current entity resolver, or null if none\r
- * has been registered.\r
- * @see #setEntityResolver\r
- */\r
- public EntityResolver getEntityResolver ();\r
-\r
-\r
- /**\r
- * Allow an application to register a DTD event handler.\r
- *\r
- * <p>If the application does not register a DTD handler, all DTD\r
- * events reported by the SAX parser will be silently ignored.</p>\r
- *\r
- * <p>Applications may register a new or different handler in the\r
- * middle of a parse, and the SAX parser must begin using the new\r
- * handler immediately.</p>\r
- *\r
- * @param handler The DTD handler.\r
- * @exception java.lang.NullPointerException If the handler \r
- * argument is null.\r
- * @see #getDTDHandler\r
- */\r
- public void setDTDHandler (DTDHandler handler);\r
-\r
-\r
- /**\r
- * Return the current DTD handler.\r
- *\r
- * @return The current DTD handler, or null if none\r
- * has been registered.\r
- * @see #setDTDHandler\r
- */\r
- public DTDHandler getDTDHandler ();\r
-\r
-\r
- /**\r
- * Allow an application to register a content event handler.\r
- *\r
- * <p>If the application does not register a content handler, all\r
- * content events reported by the SAX parser will be silently\r
- * ignored.</p>\r
- *\r
- * <p>Applications may register a new or different handler in the\r
- * middle of a parse, and the SAX parser must begin using the new\r
- * handler immediately.</p>\r
- *\r
- * @param handler The content handler.\r
- * @exception java.lang.NullPointerException If the handler \r
- * argument is null.\r
- * @see #getContentHandler\r
- */\r
- public void setContentHandler (ContentHandler handler);\r
-\r
-\r
- /**\r
- * Return the current content handler.\r
- *\r
- * @return The current content handler, or null if none\r
- * has been registered.\r
- * @see #setContentHandler\r
- */\r
- public ContentHandler getContentHandler ();\r
-\r
-\r
- /**\r
- * Allow an application to register an error event handler.\r
- *\r
- * <p>If the application does not register an error handler, all\r
- * error events reported by the SAX parser will be silently\r
- * ignored; however, normal processing may not continue. It is\r
- * highly recommended that all SAX applications implement an\r
- * error handler to avoid unexpected bugs.</p>\r
- *\r
- * <p>Applications may register a new or different handler in the\r
- * middle of a parse, and the SAX parser must begin using the new\r
- * handler immediately.</p>\r
- *\r
- * @param handler The error handler.\r
- * @exception java.lang.NullPointerException If the handler \r
- * argument is null.\r
- * @see #getErrorHandler\r
- */\r
- public void setErrorHandler (ErrorHandler handler);\r
-\r
-\r
- /**\r
- * Return the current error handler.\r
- *\r
- * @return The current error handler, or null if none\r
- * has been registered.\r
- * @see #setErrorHandler\r
- */\r
- public ErrorHandler getErrorHandler ();\r
-\r
-\r
-\f\r
- ////////////////////////////////////////////////////////////////////\r
- // Parsing.\r
- ////////////////////////////////////////////////////////////////////\r
-\r
- /**\r
- * Parse an XML document.\r
- *\r
- * <p>The application can use this method to instruct the XML\r
- * reader to begin parsing an XML document from any valid input\r
- * source (a character stream, a byte stream, or a URI).</p>\r
- *\r
- * <p>Applications may not invoke this method while a parse is in\r
- * progress (they should create a new XMLReader instead for each\r
- * nested XML document). Once a parse is complete, an\r
- * application may reuse the same XMLReader object, possibly with a\r
- * different input source.</p>\r
- *\r
- * <p>During the parse, the XMLReader will provide information\r
- * about the XML document through the registered event\r
- * handlers.</p>\r
- *\r
- * <p>This method is synchronous: it will not return until parsing\r
- * has ended. If a client application wants to terminate \r
- * parsing early, it should throw an exception.</p>\r
- *\r
- * @param source The input source for the top-level of the\r
- * XML document.\r
- * @exception org.xml.sax.SAXException Any SAX exception, possibly\r
- * wrapping another exception.\r
- * @exception java.io.IOException An IO exception from the parser,\r
- * possibly from a byte stream or character stream\r
- * supplied by the application.\r
- * @see org.xml.sax.InputSource\r
- * @see #parse(java.lang.String)\r
- * @see #setEntityResolver\r
- * @see #setDTDHandler\r
- * @see #setContentHandler\r
- * @see #setErrorHandler \r
- */\r
- public void parse (InputSource input)\r
- throws IOException, SAXException;\r
-\r
-\r
- /**\r
- * Parse an XML document from a system identifier (URI).\r
- *\r
- * <p>This method is a shortcut for the common case of reading a\r
- * document from a system identifier. It is the exact\r
- * equivalent of the following:</p>\r
- *\r
- * <pre>\r
- * parse(new InputSource(systemId));\r
- * </pre>\r
- *\r
- * <p>If the system identifier is a URL, it must be fully resolved\r
- * by the application before it is passed to the parser.</p>\r
- *\r
- * @param systemId The system identifier (URI).\r
- * @exception org.xml.sax.SAXException Any SAX exception, possibly\r
- * wrapping another exception.\r
- * @exception java.io.IOException An IO exception from the parser,\r
- * possibly from a byte stream or character stream\r
- * supplied by the application.\r
- * @see #parse(org.xml.sax.InputSource)\r
- */\r
- public void parse (String systemId)\r
- throws IOException, SAXException;\r
-\r
-}\r
-\r
-// end of XMLReader.java\r
projects / msp430-gcc.git / blobdiff