1 /* 2 * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 // SAX parser interface. 27 // http://www.saxproject.org 28 // No warranty; no copyright -- use this as you will. 29 // $Id: Parser.java,v 1.2 2004/11/03 22:55:32 jsuttor Exp $ 30 31 package org.xml.sax; 32 33 import java.io.IOException; 34 import java.util.Locale; 35 36 37 /** 38 * Basic interface for SAX (Simple API for XML) parsers. 39 * 40 * <blockquote> 41 * <em>This module, both source code and documentation, is in the 42 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 43 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> 44 * for further information. 45 * </blockquote> 46 * 47 * <p>This was the main event supplier interface for SAX1; it has 48 * been replaced in SAX2 by {@link org.xml.sax.XMLReader XMLReader}, 49 * which includes Namespace support and sophisticated configurability 50 * and extensibility.</p> 51 * 52 * <p>All SAX1 parsers must implement this basic interface: it allows 53 * applications to register handlers for different types of events 54 * and to initiate a parse from a URI, or a character stream.</p> 55 * 56 * <p>All SAX1 parsers must also implement a zero-argument constructor 57 * (though other constructors are also allowed).</p> 58 * 59 * <p>SAX1 parsers are reusable but not re-entrant: the application 60 * may reuse a parser object (possibly with a different input source) 61 * once the first parse has completed successfully, but it may not 62 * invoke the parse() methods recursively within a parse.</p> 63 * 64 * @deprecated This interface has been replaced by the SAX2 65 * {@link org.xml.sax.XMLReader XMLReader} 66 * interface, which includes Namespace support. 67 * @since 1.4, SAX 1.0 68 * @author David Megginson 69 * @see org.xml.sax.EntityResolver 70 * @see org.xml.sax.DTDHandler 71 * @see org.xml.sax.DocumentHandler 72 * @see org.xml.sax.ErrorHandler 73 * @see org.xml.sax.HandlerBase 74 * @see org.xml.sax.InputSource 75 */ 76 @Deprecated(since="1.5") 77 public interface Parser 78 { 79 80 /** 81 * Allow an application to request a locale for errors and warnings. 82 * 83 * <p>SAX parsers are not required to provide localisation for errors 84 * and warnings; if they cannot support the requested locale, 85 * however, they must throw a SAX exception. Applications may 86 * not request a locale change in the middle of a parse.</p> 87 * 88 * @param locale A Java Locale object. 89 * @exception org.xml.sax.SAXException Throws an exception 90 * (using the previous or default locale) if the 91 * requested locale is not supported. 92 * @see org.xml.sax.SAXException 93 * @see org.xml.sax.SAXParseException 94 */ setLocale(Locale locale)95 public abstract void setLocale (Locale locale) 96 throws SAXException; 97 98 99 /** 100 * Allow an application to register a custom entity resolver. 101 * 102 * <p>If the application does not register an entity resolver, the 103 * SAX parser will resolve system identifiers and open connections 104 * to entities itself (this is the default behaviour implemented in 105 * HandlerBase).</p> 106 * 107 * <p>Applications may register a new or different entity resolver 108 * in the middle of a parse, and the SAX parser must begin using 109 * the new resolver immediately.</p> 110 * 111 * @param resolver The object for resolving entities. 112 * @see EntityResolver 113 * @see HandlerBase 114 */ setEntityResolver(EntityResolver resolver)115 public abstract void setEntityResolver (EntityResolver resolver); 116 117 118 /** 119 * Allow an application to register a DTD event handler. 120 * 121 * <p>If the application does not register a DTD handler, all DTD 122 * events reported by the SAX parser will be silently 123 * ignored (this is the default behaviour implemented by 124 * HandlerBase).</p> 125 * 126 * <p>Applications may register a new or different 127 * handler in the middle of a parse, and the SAX parser must 128 * begin using the new handler immediately.</p> 129 * 130 * @param handler The DTD handler. 131 * @see DTDHandler 132 * @see HandlerBase 133 */ setDTDHandler(DTDHandler handler)134 public abstract void setDTDHandler (DTDHandler handler); 135 136 137 /** 138 * Allow an application to register a document event handler. 139 * 140 * <p>If the application does not register a document handler, all 141 * document events reported by the SAX parser will be silently 142 * ignored (this is the default behaviour implemented by 143 * HandlerBase).</p> 144 * 145 * <p>Applications may register a new or different handler in the 146 * middle of a parse, and the SAX parser must begin using the new 147 * handler immediately.</p> 148 * 149 * @param handler The document handler. 150 * @see DocumentHandler 151 * @see HandlerBase 152 */ setDocumentHandler(DocumentHandler handler)153 public abstract void setDocumentHandler (DocumentHandler handler); 154 155 156 /** 157 * Allow an application to register an error event handler. 158 * 159 * <p>If the application does not register an error event handler, 160 * all error events reported by the SAX parser will be silently 161 * ignored, except for fatalError, which will throw a SAXException 162 * (this is the default behaviour implemented by HandlerBase).</p> 163 * 164 * <p>Applications may register a new or different handler in the 165 * middle of a parse, and the SAX parser must begin using the new 166 * handler immediately.</p> 167 * 168 * @param handler The error handler. 169 * @see ErrorHandler 170 * @see SAXException 171 * @see HandlerBase 172 */ setErrorHandler(ErrorHandler handler)173 public abstract void setErrorHandler (ErrorHandler handler); 174 175 176 /** 177 * Parse an XML document. 178 * 179 * <p>The application can use this method to instruct the SAX parser 180 * to begin parsing an XML document from any valid input 181 * source (a character stream, a byte stream, or a URI).</p> 182 * 183 * <p>Applications may not invoke this method while a parse is in 184 * progress (they should create a new Parser instead for each 185 * additional XML document). Once a parse is complete, an 186 * application may reuse the same Parser object, possibly with a 187 * different input source.</p> 188 * 189 * @param source The input source for the top-level of the 190 * XML document. 191 * @exception org.xml.sax.SAXException Any SAX exception, possibly 192 * wrapping another exception. 193 * @exception java.io.IOException An IO exception from the parser, 194 * possibly from a byte stream or character stream 195 * supplied by the application. 196 * @see org.xml.sax.InputSource 197 * @see #parse(java.lang.String) 198 * @see #setEntityResolver 199 * @see #setDTDHandler 200 * @see #setDocumentHandler 201 * @see #setErrorHandler 202 */ parse(InputSource source)203 public abstract void parse (InputSource source) 204 throws SAXException, IOException; 205 206 207 /** 208 * Parse an XML document from a system identifier (URI). 209 * 210 * <p>This method is a shortcut for the common case of reading a 211 * document from a system identifier. It is the exact 212 * equivalent of the following:</p> 213 * 214 * <pre> 215 * parse(new InputSource(systemId)); 216 * </pre> 217 * 218 * <p>If the system identifier is a URL, it must be fully resolved 219 * by the application before it is passed to the parser.</p> 220 * 221 * @param systemId The system identifier (URI). 222 * @exception org.xml.sax.SAXException Any SAX exception, possibly 223 * wrapping another exception. 224 * @exception java.io.IOException An IO exception from the parser, 225 * possibly from a byte stream or character stream 226 * supplied by the application. 227 * @see #parse(org.xml.sax.InputSource) 228 */ parse(String systemId)229 public abstract void parse (String systemId) 230 throws SAXException, IOException; 231 232 } 233 234 // end of Parser.java 235