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