Java tutorial
/* * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ // SAX parser interface. // http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id: Parser.java,v 1.2 2004/11/03 22:55:32 jsuttor 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> * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> * for further information. * </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 1.4, SAX 1.0 * @author David Megginson * @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 */ @Deprecated(since = "1.5") 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