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