001// SAX parser interface. 002// No warranty; no copyright -- use this as you will. 003// $Id: Parser.java,v 1.1 2001/03/05 21:40:06 jstrachan Exp $ 004 005package org.xml.sax; 006 007import java.io.IOException; 008import java.util.Locale; 009 010 011/** 012 * Basic interface for SAX (Simple API for XML) parsers. 013 * 014 * <blockquote> 015 * <em>This module, both source code and documentation, is in the 016 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 017 * </blockquote> 018 * 019 * <p>This was the main event supplier interface for SAX1; it has 020 * been replaced in SAX2 by {@link org.xml.sax.XMLReader XMLReader}, 021 * which includes Namespace support and sophisticated configurability 022 * and extensibility.</p> 023 * 024 * <p>All SAX1 parsers must implement this basic interface: it allows 025 * applications to register handlers for different types of events 026 * and to initiate a parse from a URI, or a character stream.</p> 027 * 028 * <p>All SAX1 parsers must also implement a zero-argument constructor 029 * (though other constructors are also allowed).</p> 030 * 031 * <p>SAX1 parsers are reusable but not re-entrant: the application 032 * may reuse a parser object (possibly with a different input source) 033 * once the first parse has completed successfully, but it may not 034 * invoke the parse() methods recursively within a parse.</p> 035 * 036 * @deprecated This interface has been replaced by the SAX2 037 * {@link org.xml.sax.XMLReader XMLReader} 038 * interface, which includes Namespace support. 039 * @since SAX 1.0 040 * @author David Megginson, 041 * <a href="mailto:sax@megginson.com">sax@megginson.com</a> 042 * @version 2.0 043 * @see org.xml.sax.EntityResolver 044 * @see org.xml.sax.DTDHandler 045 * @see org.xml.sax.DocumentHandler 046 * @see org.xml.sax.ErrorHandler 047 * @see org.xml.sax.HandlerBase 048 * @see org.xml.sax.InputSource 049 */ 050public interface Parser 051{ 052 053 /** 054 * Allow an application to request a locale for errors and warnings. 055 * 056 * <p>SAX parsers are not required to provide localisation for errors 057 * and warnings; if they cannot support the requested locale, 058 * however, they must throw a SAX exception. Applications may 059 * not request a locale change in the middle of a parse.</p> 060 * 061 * @param locale A Java Locale object. 062 * @exception org.xml.sax.SAXException Throws an exception 063 * (using the previous or default locale) if the 064 * requested locale is not supported. 065 * @see org.xml.sax.SAXException 066 * @see org.xml.sax.SAXParseException 067 */ 068 public abstract void setLocale (Locale locale) 069 throws SAXException; 070 071 072 /** 073 * Allow an application to register a custom entity resolver. 074 * 075 * <p>If the application does not register an entity resolver, the 076 * SAX parser will resolve system identifiers and open connections 077 * to entities itself (this is the default behaviour implemented in 078 * HandlerBase).</p> 079 * 080 * <p>Applications may register a new or different entity resolver 081 * in the middle of a parse, and the SAX parser must begin using 082 * the new resolver immediately.</p> 083 * 084 * @param resolver The object for resolving entities. 085 * @see EntityResolver 086 * @see HandlerBase 087 */ 088 public abstract void setEntityResolver (EntityResolver resolver); 089 090 091 /** 092 * Allow an application to register a DTD event handler. 093 * 094 * <p>If the application does not register a DTD handler, all DTD 095 * events reported by the SAX parser will be silently 096 * ignored (this is the default behaviour implemented by 097 * HandlerBase).</p> 098 * 099 * <p>Applications may register a new or different 100 * handler in the middle of a parse, and the SAX parser must 101 * begin using the new handler immediately.</p> 102 * 103 * @param handler The DTD handler. 104 * @see DTDHandler 105 * @see HandlerBase 106 */ 107 public abstract void setDTDHandler (DTDHandler handler); 108 109 110 /** 111 * Allow an application to register a document event handler. 112 * 113 * <p>If the application does not register a document handler, all 114 * document events reported by the SAX parser will be silently 115 * ignored (this is the default behaviour implemented by 116 * HandlerBase).</p> 117 * 118 * <p>Applications may register a new or different handler in the 119 * middle of a parse, and the SAX parser must begin using the new 120 * handler immediately.</p> 121 * 122 * @param handler The document handler. 123 * @see DocumentHandler 124 * @see HandlerBase 125 */ 126 public abstract void setDocumentHandler (DocumentHandler handler); 127 128 129 /** 130 * Allow an application to register an error event handler. 131 * 132 * <p>If the application does not register an error event handler, 133 * all error events reported by the SAX parser will be silently 134 * ignored, except for fatalError, which will throw a SAXException 135 * (this is the default behaviour implemented by HandlerBase).</p> 136 * 137 * <p>Applications may register a new or different handler in the 138 * middle of a parse, and the SAX parser must begin using the new 139 * handler immediately.</p> 140 * 141 * @param handler The error handler. 142 * @see ErrorHandler 143 * @see SAXException 144 * @see HandlerBase 145 */ 146 public abstract void setErrorHandler (ErrorHandler handler); 147 148 149 /** 150 * Parse an XML document. 151 * 152 * <p>The application can use this method to instruct the SAX parser 153 * to begin parsing an XML document from any valid input 154 * source (a character stream, a byte stream, or a URI).</p> 155 * 156 * <p>Applications may not invoke this method while a parse is in 157 * progress (they should create a new Parser instead for each 158 * additional XML document). Once a parse is complete, an 159 * application may reuse the same Parser object, possibly with a 160 * different input source.</p> 161 * 162 * @param source The input source for the top-level of the 163 * XML document. 164 * @exception org.xml.sax.SAXException Any SAX exception, possibly 165 * wrapping another exception. 166 * @exception java.io.IOException An IO exception from the parser, 167 * possibly from a byte stream or character stream 168 * supplied by the application. 169 * @see org.xml.sax.InputSource 170 * @see #parse(java.lang.String) 171 * @see #setEntityResolver 172 * @see #setDTDHandler 173 * @see #setDocumentHandler 174 * @see #setErrorHandler 175 */ 176 public abstract void parse (InputSource source) 177 throws SAXException, IOException; 178 179 180 /** 181 * Parse an XML document from a system identifier (URI). 182 * 183 * <p>This method is a shortcut for the common case of reading a 184 * document from a system identifier. It is the exact 185 * equivalent of the following:</p> 186 * 187 * <pre> 188 * parse(new InputSource(systemId)); 189 * </pre> 190 * 191 * <p>If the system identifier is a URL, it must be fully resolved 192 * by the application before it is passed to the parser.</p> 193 * 194 * @param systemId The system identifier (URI). 195 * @exception org.xml.sax.SAXException Any SAX exception, possibly 196 * wrapping another exception. 197 * @exception java.io.IOException An IO exception from the parser, 198 * possibly from a byte stream or character stream 199 * supplied by the application. 200 * @see #parse(org.xml.sax.InputSource) 201 */ 202 public abstract void parse (String systemId) 203 throws SAXException, IOException; 204 205} 206 207// end of Parser.java