1 /* 2 * Copyright (c) 2000, 2019, 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 package org.xml.sax; 27 28 import java.io.IOException; 29 import java.util.Locale; 30 31 32 /** 33 * Basic interface for SAX (Simple API for XML) parsers. 34 * 35 * <p>This was the main event supplier interface for SAX1; it has 36 * been replaced in SAX2 by {@link org.xml.sax.XMLReader XMLReader}, 37 * which includes Namespace support and sophisticated configurability 38 * and extensibility.</p> 39 * 40 * <p>All SAX1 parsers must implement this basic interface: it allows 41 * applications to register handlers for different types of events 42 * and to initiate a parse from a URI, or a character stream.</p> 43 * 44 * <p>All SAX1 parsers must also implement a zero-argument constructor 45 * (though other constructors are also allowed).</p> 46 * 47 * <p>SAX1 parsers are reusable but not re-entrant: the application 48 * may reuse a parser object (possibly with a different input source) 49 * once the first parse has completed successfully, but it may not 50 * invoke the parse() methods recursively within a parse.</p> 51 * 52 * @deprecated This interface has been replaced by the SAX2 53 * {@link org.xml.sax.XMLReader XMLReader} 54 * interface, which includes Namespace support. 55 * @since 1.4, SAX 1.0 56 * @author David Megginson 57 * @see org.xml.sax.EntityResolver 58 * @see org.xml.sax.DTDHandler 59 * @see org.xml.sax.DocumentHandler 60 * @see org.xml.sax.ErrorHandler 61 * @see org.xml.sax.HandlerBase 62 * @see org.xml.sax.InputSource 63 */ 64 @Deprecated(since="1.5") 65 public interface Parser 66 { 67 68 /** 69 * Allow an application to request a locale for errors and warnings. 70 * 71 * <p>SAX parsers are not required to provide localisation for errors 72 * and warnings; if they cannot support the requested locale, 73 * however, they must throw a SAX exception. Applications may 74 * not request a locale change in the middle of a parse.</p> 75 * 76 * @param locale A Java Locale object. 77 * @exception org.xml.sax.SAXException Throws an exception 78 * (using the previous or default locale) if the 79 * requested locale is not supported. 80 * @see org.xml.sax.SAXException 81 * @see org.xml.sax.SAXParseException 82 */ 83 public abstract void setLocale (Locale locale) 84 throws SAXException; 85 86 87 /** 88 * Allow an application to register a custom entity resolver. 89 * 90 * <p>If the application does not register an entity resolver, the 91 * SAX parser will resolve system identifiers and open connections 92 * to entities itself (this is the default behaviour implemented in 93 * HandlerBase).</p> 94 * 95 * <p>Applications may register a new or different entity resolver 96 * in the middle of a parse, and the SAX parser must begin using 97 * the new resolver immediately.</p> 98 * 99 * @param resolver The object for resolving entities. 100 * @see EntityResolver 101 * @see HandlerBase 102 */ 103 public abstract void setEntityResolver (EntityResolver resolver); 104 105 106 /** 107 * Allow an application to register a DTD event handler. 108 * 109 * <p>If the application does not register a DTD handler, all DTD 110 * events reported by the SAX parser will be silently 111 * ignored (this is the default behaviour implemented by 112 * HandlerBase).</p> 113 * 114 * <p>Applications may register a new or different 115 * handler in the middle of a parse, and the SAX parser must 116 * begin using the new handler immediately.</p> 117 * 118 * @param handler The DTD handler. 119 * @see DTDHandler 120 * @see HandlerBase 121 */ 122 public abstract void setDTDHandler (DTDHandler handler); 123 124 125 /** 126 * Allow an application to register a document event handler. 127 * 128 * <p>If the application does not register a document handler, all 129 * document events reported by the SAX parser will be silently 130 * ignored (this is the default behaviour implemented by 131 * HandlerBase).</p> 132 * 133 * <p>Applications may register a new or different handler in the 134 * middle of a parse, and the SAX parser must begin using the new 135 * handler immediately.</p> 136 * 137 * @param handler The document handler. 138 * @see DocumentHandler 139 * @see HandlerBase 140 */ 141 public abstract void setDocumentHandler (DocumentHandler handler); 142 143 144 /** 145 * Allow an application to register an error event handler. 146 * 147 * <p>If the application does not register an error event handler, 148 * all error events reported by the SAX parser will be silently 149 * ignored, except for fatalError, which will throw a SAXException 150 * (this is the default behaviour implemented by HandlerBase).</p> 151 * 152 * <p>Applications may register a new or different handler in the 153 * middle of a parse, and the SAX parser must begin using the new 154 * handler immediately.</p> 155 * 156 * @param handler The error handler. 157 * @see ErrorHandler 158 * @see SAXException 159 * @see HandlerBase 160 */ 161 public abstract void setErrorHandler (ErrorHandler handler); 162 163 164 /** 165 * Parse an XML document. 166 * 167 * <p>The application can use this method to instruct the SAX parser 168 * to begin parsing an XML document from any valid input 169 * source (a character stream, a byte stream, or a URI).</p> 170 * 171 * <p>Applications may not invoke this method while a parse is in 172 * progress (they should create a new Parser instead for each 173 * additional XML document). Once a parse is complete, an 174 * application may reuse the same Parser object, possibly with a 175 * different input source.</p> 176 * 177 * @param source The input source for the top-level of the 178 * XML document. 179 * @exception org.xml.sax.SAXException Any SAX exception, possibly 180 * wrapping another exception. 181 * @exception java.io.IOException An IO exception from the parser, 182 * possibly from a byte stream or character stream 183 * supplied by the application. 184 * @see org.xml.sax.InputSource 185 * @see #parse(java.lang.String) 186 * @see #setEntityResolver 187 * @see #setDTDHandler 188 * @see #setDocumentHandler 189 * @see #setErrorHandler 190 */ 191 public abstract void parse (InputSource source) 192 throws SAXException, IOException; 193 194 195 /** 196 * Parse an XML document from a system identifier (URI). 197 * 198 * <p>This method is a shortcut for the common case of reading a 199 * document from a system identifier. It is the exact 200 * equivalent of the following:</p> 201 * 202 * <pre> 203 * parse(new InputSource(systemId)); 204 * </pre> 205 * 206 * <p>If the system identifier is a URL, it must be fully resolved 207 * by the application before it is passed to the parser.</p> 208 * 209 * @param systemId The system identifier (URI). 210 * @exception org.xml.sax.SAXException Any SAX exception, possibly 211 * wrapping another exception. 212 * @exception java.io.IOException An IO exception from the parser, 213 * possibly from a byte stream or character stream 214 * supplied by the application. 215 * @see #parse(org.xml.sax.InputSource) 216 */ 217 public abstract void parse (String systemId) 218 throws SAXException, IOException; 219 220 } 221 222 // end of Parser.java