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