001: // SAX parser interface.
002: // http://www.saxproject.org
003: // No warranty; no copyright -- use this as you will.
004:
005: package org.xml.sax;
006:
007: import java.io.IOException;
008:
009: /**
010: * Basic interface for SAX (Simple API for XML) parsers.
011: *
012: * <blockquote>
013: * <em>This module, both source code and documentation, is in the
014: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
015: * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
016: * for further information.
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: * @version 2.0.1 (sax2r2)
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 register a custom entity resolver.
053: *
054: * <p>If the application does not register an entity resolver, the
055: * SAX parser will resolve system identifiers and open connections
056: * to entities itself (this is the default behaviour implemented in
057: * HandlerBase).</p>
058: *
059: * <p>Applications may register a new or different entity resolver
060: * in the middle of a parse, and the SAX parser must begin using
061: * the new resolver immediately.</p>
062: *
063: * @param resolver The object for resolving entities.
064: * @see EntityResolver
065: * @see HandlerBase
066: */
067: public abstract void setEntityResolver(EntityResolver resolver);
068:
069: /**
070: * Allow an application to register a DTD event handler.
071: *
072: * <p>If the application does not register a DTD handler, all DTD
073: * events reported by the SAX parser will be silently
074: * ignored (this is the default behaviour implemented by
075: * HandlerBase).</p>
076: *
077: * <p>Applications may register a new or different
078: * handler in the middle of a parse, and the SAX parser must
079: * begin using the new handler immediately.</p>
080: *
081: * @param handler The DTD handler.
082: * @see DTDHandler
083: * @see HandlerBase
084: */
085: public abstract void setDTDHandler(DTDHandler handler);
086:
087: /**
088: * Allow an application to register a document event handler.
089: *
090: * <p>If the application does not register a document handler, all
091: * document events reported by the SAX parser will be silently
092: * ignored (this is the default behaviour implemented by
093: * HandlerBase).</p>
094: *
095: * <p>Applications may register a new or different handler in the
096: * middle of a parse, and the SAX parser must begin using the new
097: * handler immediately.</p>
098: *
099: * @param handler The document handler.
100: * @see DocumentHandler
101: * @see HandlerBase
102: */
103: public abstract void setDocumentHandler(DocumentHandler handler);
104:
105: /**
106: * Allow an application to register an error event handler.
107: *
108: * <p>If the application does not register an error event handler,
109: * all error events reported by the SAX parser will be silently
110: * ignored, except for fatalError, which will throw a SAXException
111: * (this is the default behaviour implemented by HandlerBase).</p>
112: *
113: * <p>Applications may register a new or different handler in the
114: * middle of a parse, and the SAX parser must begin using the new
115: * handler immediately.</p>
116: *
117: * @param handler The error handler.
118: * @see ErrorHandler
119: * @see SAXException
120: * @see HandlerBase
121: */
122: public abstract void setErrorHandler(ErrorHandler handler);
123:
124: /**
125: * Parse an XML document.
126: *
127: * <p>The application can use this method to instruct the SAX parser
128: * to begin parsing an XML document from any valid input
129: * source (a character stream, a byte stream, or a URI).</p>
130: *
131: * <p>Applications may not invoke this method while a parse is in
132: * progress (they should create a new Parser instead for each
133: * additional XML document). Once a parse is complete, an
134: * application may reuse the same Parser object, possibly with a
135: * different input source.</p>
136: *
137: * @param source The input source for the top-level of the
138: * XML document.
139: * @exception org.xml.sax.SAXException Any SAX exception, possibly
140: * wrapping another exception.
141: * @exception j2me.io.IOException An IO exception from the parser,
142: * possibly from a byte stream or character stream
143: * supplied by the application.
144: * @see org.xml.sax.InputSource
145: * @see #parse(j2me.lang.String)
146: * @see #setEntityResolver
147: * @see #setDTDHandler
148: * @see #setDocumentHandler
149: * @see #setErrorHandler
150: */
151: public abstract void parse(InputSource source) throws SAXException,
152: IOException;
153:
154: /**
155: * Parse an XML document from a system identifier (URI).
156: *
157: * <p>This method is a shortcut for the common case of reading a
158: * document from a system identifier. It is the exact
159: * equivalent of the following:</p>
160: *
161: * <pre>
162: * parse(new InputSource(systemId));
163: * </pre>
164: *
165: * <p>If the system identifier is a URL, it must be fully resolved
166: * by the application before it is passed to the parser.</p>
167: *
168: * @param systemId The system identifier (URI).
169: * @exception org.xml.sax.SAXException Any SAX exception, possibly
170: * wrapping another exception.
171: * @exception j2me.io.IOException An IO exception from the parser,
172: * possibly from a byte stream or character stream
173: * supplied by the application.
174: * @see #parse(org.xml.sax.InputSource)
175: */
176: public abstract void parse(String systemId) throws SAXException,
177: IOException;
178:
179: }
180:
181: // end of Parser.java
|