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 public interface Parser 77 { 78 79 /** 80 * Allow an application to request a locale for errors and warnings. 81 * 82 * <p>SAX parsers are not required to provide localisation for errors 83 * and warnings; if they cannot support the requested locale, 84 * however, they must throw a SAX exception. Applications may 85 * not request a locale change in the middle of a parse.</p> 86 * 87 * @param locale A Java Locale object. 88 * @exception org.xml.sax.SAXException Throws an exception 89 * (using the previous or default locale) if the 90 * requested locale is not supported. 91 * @see org.xml.sax.SAXException 92 * @see org.xml.sax.SAXParseException 93 */ 94 public abstract void setLocale (Locale locale) 95 throws SAXException; 96 97 98 /** 99 * Allow an application to register a custom entity resolver. 100 * 101 * <p>If the application does not register an entity resolver, the 102 * SAX parser will resolve system identifiers and open connections 103 * to entities itself (this is the default behaviour implemented in 104 * HandlerBase).</p> 105 * 106 * <p>Applications may register a new or different entity resolver 107 * in the middle of a parse, and the SAX parser must begin using 108 * the new resolver immediately.</p> 109 * 110 * @param resolver The object for resolving entities. 111 * @see EntityResolver 112 * @see HandlerBase 113 */ 114 public abstract void setEntityResolver (EntityResolver resolver); 115 116 117 /** 118 * Allow an application to register a DTD event handler. 119 * 120 * <p>If the application does not register a DTD handler, all DTD 121 * events reported by the SAX parser will be silently 122 * ignored (this is the default behaviour implemented by 123 * HandlerBase).</p> 124 * 125 * <p>Applications may register a new or different 126 * handler in the middle of a parse, and the SAX parser must 127 * begin using the new handler immediately.</p> 128 * 129 * @param handler The DTD handler. 130 * @see DTDHandler 131 * @see HandlerBase 132 */ 133 public abstract void setDTDHandler (DTDHandler handler); 134 135 136 /** 137 * Allow an application to register a document event handler. 138 * 139 * <p>If the application does not register a document handler, all 140 * document events reported by the SAX parser will be silently 141 * ignored (this is the default behaviour implemented by 142 * HandlerBase).</p> 143 * 144 * <p>Applications may register a new or different handler in the 145 * middle of a parse, and the SAX parser must begin using the new 146 * handler immediately.</p> 147 * 148 * @param handler The document handler. 149 * @see DocumentHandler 150 * @see HandlerBase 151 */ 152 public abstract void setDocumentHandler (DocumentHandler handler); 153 154 155 /** 156 * Allow an application to register an error event handler. 157 * 158 * <p>If the application does not register an error event handler, 159 * all error events reported by the SAX parser will be silently 160 * ignored, except for fatalError, which will throw a SAXException 161 * (this is the default behaviour implemented by HandlerBase).</p> 162 * 163 * <p>Applications may register a new or different handler in the 164 * middle of a parse, and the SAX parser must begin using the new 165 * handler immediately.</p> 166 * 167 * @param handler The error handler. 168 * @see ErrorHandler 169 * @see SAXException 170 * @see HandlerBase 171 */ 172 public abstract void setErrorHandler (ErrorHandler handler); 173 174 175 /** 176 * Parse an XML document. 177 * 178 * <p>The application can use this method to instruct the SAX parser 179 * to begin parsing an XML document from any valid input 180 * source (a character stream, a byte stream, or a URI).</p> 181 * 182 * <p>Applications may not invoke this method while a parse is in 183 * progress (they should create a new Parser instead for each 184 * additional XML document). Once a parse is complete, an 185 * application may reuse the same Parser object, possibly with a 186 * different input source.</p> 187 * 188 * @param source The input source for the top-level of the 189 * XML document. 190 * @exception org.xml.sax.SAXException Any SAX exception, possibly 191 * wrapping another exception. 192 * @exception java.io.IOException An IO exception from the parser, 193 * possibly from a byte stream or character stream 194 * supplied by the application. 195 * @see org.xml.sax.InputSource 196 * @see #parse(java.lang.String) 197 * @see #setEntityResolver 198 * @see #setDTDHandler 199 * @see #setDocumentHandler 200 * @see #setErrorHandler 201 */ 202 public abstract void parse (InputSource source) 203 throws SAXException, IOException; 204 205 206 /** 207 * Parse an XML document from a system identifier (URI). 208 * 209 * <p>This method is a shortcut for the common case of reading a 210 * document from a system identifier. It is the exact 211 * equivalent of the following:</p> 212 * 213 * <pre> 214 * parse(new InputSource(systemId)); 215 * </pre> 216 * 217 * <p>If the system identifier is a URL, it must be fully resolved 218 * by the application before it is passed to the parser.</p> 219 * 220 * @param systemId The system identifier (URI). 221 * @exception org.xml.sax.SAXException Any SAX exception, possibly 222 * wrapping another exception. 223 * @exception java.io.IOException An IO exception from the parser, 224 * possibly from a byte stream or character stream 225 * supplied by the application. 226 * @see #parse(org.xml.sax.InputSource) 227 */ 228 public abstract void parse (String systemId) 229 throws SAXException, IOException; 230 231 } 232 233 // end of Parser.java