// SAX parser interface. | |
// No warranty; no copyright -- use this as you will. | |
// $Id: Parser.java,v 1.1 2000/10/02 02:43:17 sboag Exp $ | |
package org.xml.sax; | |
import java.io.IOException; | |
import java.util.Locale; | |
/** | |
* Basic interface for SAX (Simple API for XML) parsers. | |
* | |
* <blockquote> | |
* <em>This module, both source code and documentation, is in the | |
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> | |
* </blockquote> | |
* | |
* <p>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.</p> | |
* | |
* <p>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.</p> | |
* | |
* <p>All SAX1 parsers must also implement a zero-argument constructor | |
* (though other constructors are also allowed).</p> | |
* | |
* <p>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.</p> | |
* | |
* @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, | |
* <a href="mailto:sax@megginson.com">sax@megginson.com</a> | |
* @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. | |
* | |
* <p>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.</p> | |
* | |
* @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. | |
* | |
* <p>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).</p> | |
* | |
* <p>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.</p> | |
* | |
* @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. | |
* | |
* <p>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).</p> | |
* | |
* <p>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.</p> | |
* | |
* @param handler The DTD handler. | |
* @see DTDHandler | |
* @see HandlerBase | |
*/ | |
public abstract void setDTDHandler (DTDHandler handler); | |
/** | |
* Allow an application to register a document event handler. | |
* | |
* <p>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).</p> | |
* | |
* <p>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.</p> | |
* | |
* @param handler The document handler. | |
* @see DocumentHandler | |
* @see HandlerBase | |
*/ | |
public abstract void setDocumentHandler (DocumentHandler handler); | |
/** | |
* Allow an application to register an error event handler. | |
* | |
* <p>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).</p> | |
* | |
* <p>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.</p> | |
* | |
* @param handler The error handler. | |
* @see ErrorHandler | |
* @see SAXException | |
* @see HandlerBase | |
*/ | |
public abstract void setErrorHandler (ErrorHandler handler); | |
/** | |
* Parse an XML document. | |
* | |
* <p>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).</p> | |
* | |
* <p>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.</p> | |
* | |
* @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). | |
* | |
* <p>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:</p> | |
* | |
* <pre> | |
* parse(new InputSource(systemId)); | |
* </pre> | |
* | |
* <p>If the system identifier is a URL, it must be fully resolved | |
* by the application before it is passed to the parser.</p> | |
* | |
* @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 |