- * This module, both source code and documentation, is in the - * Public Domain, and comes with NO WARRANTY. - *- * - *
This was the main event supplier interface for SAX1; it has - * been replaced in SAX2 by {@link org.xml.sax.XMLReader XMLReader}, - * which includes Namespace support and sophisticated configurability - * and extensibility.
- * - *All SAX1 parsers must implement this basic interface: it allows - * applications to register handlers for different types of events - * and to initiate a parse from a URI, or a character stream.
- * - *All SAX1 parsers must also implement a zero-argument constructor - * (though other constructors are also allowed).
- * - *SAX1 parsers are reusable but not re-entrant: the application - * may reuse a parser object (possibly with a different input source) - * once the first parse has completed successfully, but it may not - * invoke the parse() methods recursively within a parse.
- * - * @deprecated This interface has been replaced by the SAX2 - * {@link org.xml.sax.XMLReader XMLReader} - * interface, which includes Namespace support. - * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @version 2.0 - * @see org.xml.sax.EntityResolver - * @see org.xml.sax.DTDHandler - * @see org.xml.sax.DocumentHandler - * @see org.xml.sax.ErrorHandler - * @see org.xml.sax.HandlerBase - * @see org.xml.sax.InputSource - */ -public interface Parser -{ - - /** - * Allow an application to request a locale for errors and warnings. - * - *SAX parsers are not required to provide localisation for errors - * and warnings; if they cannot support the requested locale, - * however, they must throw a SAX exception. Applications may - * not request a locale change in the middle of a parse.
- * - * @param locale A Java Locale object. - * @exception org.xml.sax.SAXException Throws an exception - * (using the previous or default locale) if the - * requested locale is not supported. - * @see org.xml.sax.SAXException - * @see org.xml.sax.SAXParseException - */ - public abstract void setLocale (Locale locale) - throws SAXException; - - - /** - * Allow an application to register a custom entity resolver. - * - *If the application does not register an entity resolver, the - * SAX parser will resolve system identifiers and open connections - * to entities itself (this is the default behaviour implemented in - * HandlerBase).
- * - *Applications may register a new or different entity resolver - * in the middle of a parse, and the SAX parser must begin using - * the new resolver immediately.
- * - * @param resolver The object for resolving entities. - * @see EntityResolver - * @see HandlerBase - */ - public abstract void setEntityResolver (EntityResolver resolver); - - - /** - * Allow an application to register a DTD event handler. - * - *If the application does not register a DTD handler, all DTD - * events reported by the SAX parser will be silently - * ignored (this is the default behaviour implemented by - * HandlerBase).
- * - *Applications may register a new or different - * handler in the middle of a parse, and the SAX parser must - * begin using the new handler immediately.
- * - * @param handler The DTD handler. - * @see DTDHandler - * @see HandlerBase - */ - public abstract void setDTDHandler (DTDHandler handler); - - - /** - * Allow an application to register a document event handler. - * - *If the application does not register a document handler, all - * document events reported by the SAX parser will be silently - * ignored (this is the default behaviour implemented by - * HandlerBase).
- * - *Applications may register a new or different handler in the - * middle of a parse, and the SAX parser must begin using the new - * handler immediately.
- * - * @param handler The document handler. - * @see DocumentHandler - * @see HandlerBase - */ - public abstract void setDocumentHandler (DocumentHandler handler); - - - /** - * Allow an application to register an error event handler. - * - *If the application does not register an error event handler, - * all error events reported by the SAX parser will be silently - * ignored, except for fatalError, which will throw a SAXException - * (this is the default behaviour implemented by HandlerBase).
- * - *Applications may register a new or different handler in the - * middle of a parse, and the SAX parser must begin using the new - * handler immediately.
- * - * @param handler The error handler. - * @see ErrorHandler - * @see SAXException - * @see HandlerBase - */ - public abstract void setErrorHandler (ErrorHandler handler); - - - /** - * Parse an XML document. - * - *The application can use this method to instruct the SAX parser - * to begin parsing an XML document from any valid input - * source (a character stream, a byte stream, or a URI).
- * - *Applications may not invoke this method while a parse is in - * progress (they should create a new Parser instead for each - * additional XML document). Once a parse is complete, an - * application may reuse the same Parser object, possibly with a - * different input source.
- * - * @param source The input source for the top-level of the - * XML document. - * @exception org.xml.sax.SAXException Any SAX exception, possibly - * wrapping another exception. - * @exception java.io.IOException An IO exception from the parser, - * possibly from a byte stream or character stream - * supplied by the application. - * @see org.xml.sax.InputSource - * @see #parse(java.lang.String) - * @see #setEntityResolver - * @see #setDTDHandler - * @see #setDocumentHandler - * @see #setErrorHandler - */ - public abstract void parse (InputSource source) - throws SAXException, IOException; - - - /** - * Parse an XML document from a system identifier (URI). - * - *This method is a shortcut for the common case of reading a - * document from a system identifier. It is the exact - * equivalent of the following:
- * - *- * parse(new InputSource(systemId)); - *- * - *
If the system identifier is a URL, it must be fully resolved - * by the application before it is passed to the parser.
- * - * @param systemId The system identifier (URI). - * @exception org.xml.sax.SAXException Any SAX exception, possibly - * wrapping another exception. - * @exception java.io.IOException An IO exception from the parser, - * possibly from a byte stream or character stream - * supplied by the application. - * @see #parse(org.xml.sax.InputSource) - */ - public abstract void parse (String systemId) - throws SAXException, IOException; - -} - -// end of Parser.java