Parser.java revision 286
1008N/A * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved. 1008N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1008N/A * This code is free software; you can redistribute it and/or modify it 1008N/A * under the terms of the GNU General Public License version 2 only, as 1008N/A * published by the Free Software Foundation. Oracle designates this 1008N/A * particular file as subject to the "Classpath" exception as provided 1008N/A * by Oracle in the LICENSE file that accompanied this code. 1008N/A * This code is distributed in the hope that it will be useful, but WITHOUT 1008N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1008N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1008N/A * version 2 for more details (a copy is included in the LICENSE file that 1008N/A * You should have received a copy of the GNU General Public License version 1008N/A * 2 along with this work; if not, write to the Free Software Foundation, 1008N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1008N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 1008N/A * or visit www.oracle.com if you need additional information or have any 1008N/A// No warranty; no copyright -- use this as you will. 1008N/A * Basic interface for SAX (Simple API for XML) parsers. 1008N/A * <em>This module, both source code and documentation, is in the 1008N/A * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 1008N/A * <p>This was the main event supplier interface for SAX1; it has 1008N/A * which includes Namespace support and sophisticated configurability 1008N/A * <p>All SAX1 parsers must implement this basic interface: it allows 1008N/A * applications to register handlers for different types of events 1008N/A * and to initiate a parse from a URI, or a character stream.</p> 1008N/A * <p>All SAX1 parsers must also implement a zero-argument constructor 1008N/A * (though other constructors are also allowed).</p> 1008N/A * <p>SAX1 parsers are reusable but not re-entrant: the application 1008N/A * may reuse a parser object (possibly with a different input source) 1008N/A * once the first parse has completed successfully, but it may not 1008N/A * invoke the parse() methods recursively within a parse.</p> 1008N/A * @deprecated This interface has been replaced by the SAX2 1008N/A * interface, which includes Namespace support. 1008N/A * Allow an application to request a locale for errors and warnings. 1008N/A * <p>SAX parsers are not required to provide localisation for errors 1008N/A * and warnings; if they cannot support the requested locale, 1008N/A * however, they must throw a SAX exception. Applications may 1008N/A * not request a locale change in the middle of a parse.</p> 1008N/A * @param locale A Java Locale object. 1008N/A * @exception org.xml.sax.SAXException Throws an exception 1008N/A * (using the previous or default locale) if the 1008N/A * requested locale is not supported. * 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 * <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. * 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 * <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. * 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 * <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. * 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. * <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 * @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(java.lang.String) * @see #setEntityResolver * @see #setDocumentHandler * 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> * parse(new InputSource(systemId)); * <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)