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