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