source: NonGTP/Xerces/xerces/include/xercesc/sax/Parser.hpp @ 358

Revision 358, 9.5 KB checked in by bittner, 19 years ago (diff)

xerces added

Line 
1/*
2 * Copyright 1999-2001,2004 The Apache Software Foundation.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17/*
18 * $Log: Parser.hpp,v $
19 * Revision 1.5  2004/09/08 13:56:19  peiyongz
20 * Apache License Version 2.0
21 *
22 * Revision 1.4  2003/03/07 18:10:06  tng
23 * Return a reference instead of void for operator=
24 *
25 * Revision 1.3  2002/11/04 14:56:26  tng
26 * C++ Namespace Support.
27 *
28 * Revision 1.2  2002/07/11 18:29:09  knoaman
29 * Grammar caching/preparsing - initial implementation.
30 *
31 * Revision 1.1.1.1  2002/02/01 22:22:08  peiyongz
32 * sane_include
33 *
34 * Revision 1.8  2001/05/11 13:26:24  tng
35 * Copyright update.
36 *
37 * Revision 1.7  2001/03/21 21:56:10  tng
38 * Schema: Add Schema Grammar, Schema Validator, and split the DTDValidator into DTDValidator, DTDScanner, and DTDGrammar.
39 *
40 * Revision 1.6  2000/03/02 19:54:35  roddey
41 * This checkin includes many changes done while waiting for the
42 * 1.1.0 code to be finished. I can't list them all here, but a list is
43 * available elsewhere.
44 *
45 * Revision 1.5  2000/02/24 20:12:55  abagchi
46 * Swat for removing Log from API docs
47 *
48 * Revision 1.4  2000/02/12 03:31:55  rahulj
49 * Removed duplicate CVS Log entries.
50 *
51 * Revision 1.3  2000/02/09 01:59:12  abagchi
52 * Removed private function docs, added parse docs
53 *
54 * Revision 1.2  2000/02/06 07:47:58  rahulj
55 * Year 2K copyright swat.
56 *
57 * Revision 1.1.1.1  1999/11/09 01:07:46  twl
58 * Initial checkin
59 *
60 * Revision 1.3  1999/11/08 20:45:02  rahul
61 * Swat for adding in Product name and CVS comment log variable.
62 *
63 */
64
65#ifndef PARSER_HPP
66#define PARSER_HPP
67
68#include <xercesc/util/XercesDefs.hpp>
69
70XERCES_CPP_NAMESPACE_BEGIN
71
72class DTDHandler;
73class EntityResolver;
74class DocumentHandler;
75class ErrorHandler;
76class InputSource;
77
78/**
79  * Basic interface for SAX (Simple API for XML) parsers.
80  *
81  * All SAX parsers must implement this basic interface: it allows
82  * applications to register handlers for different types of events
83  * and to initiate a parse from a URI, or a character stream.
84  *
85  * All SAX parsers must also implement a zero-argument constructor
86  * (though other constructors are also allowed).
87  *
88  * SAX parsers are reusable but not re-entrant: the application
89  * may reuse a parser object (possibly with a different input source)
90  * once the first parse has completed successfully, but it may not
91  * invoke the parse() methods recursively within a parse.
92  *
93  * @see EntityResolver#EntityResolver
94  * @see DTDHandler#DTDHandler
95  * @see DocumentHandler#DocumentHandler
96  * @see ErrorHandler#ErrorHandler
97  * @see HandlerBase#HandlerBase
98  * @see InputSource#InputSource
99  */
100
101#include <xercesc/util/XercesDefs.hpp>
102
103class SAX_EXPORT Parser
104{
105public:
106    /** @name Constructors and Destructor */
107    // -----------------------------------------------------------------------
108    //  Constructors and Destructor
109    // -----------------------------------------------------------------------
110    //@{
111    /** The default constructor */
112    Parser()
113    {
114    }
115    /** The destructor */
116    virtual ~Parser()
117    {
118    }
119    //@}
120
121    //-----------------------------------------------------------------------
122    // The parser interface
123    //-----------------------------------------------------------------------
124    /** @name The parser interfaces */
125    //@{
126  /**
127    * Allow an application to register a custom entity resolver.
128    *
129    * If the application does not register an entity resolver, the
130    * SAX parser will resolve system identifiers and open connections
131    * to entities itself (this is the default behaviour implemented in
132    * HandlerBase).
133    *
134    * Applications may register a new or different entity resolver
135    * in the middle of a parse, and the SAX parser must begin using
136    * the new resolver immediately.
137    *
138    * @param resolver The object for resolving entities.
139    * @see EntityResolver#EntityResolver
140    * @see HandlerBase#HandlerBase
141    */
142    virtual void setEntityResolver(EntityResolver* const resolver) = 0;
143
144  /**
145    * Allow an application to register a DTD event handler.
146    *
147    * If the application does not register a DTD handler, all DTD
148    * events reported by the SAX parser will be silently ignored (this
149    * is the default behaviour implemented by HandlerBase).
150    *
151    * Applications may register a new or different handler in the middle
152    * of a parse, and the SAX parser must begin using the new handler
153    * immediately.
154    *
155    * @param handler The DTD handler.
156    * @see DTDHandler#DTDHandler
157    * @see HandlerBase#HandlerBase
158    */
159    virtual void setDTDHandler(DTDHandler* const handler) = 0;
160
161  /**
162    * Allow an application to register a document event handler.
163    *
164    * If the application does not register a document handler, all
165    * document events reported by the SAX parser will be silently
166    * ignored (this is the default behaviour implemented by
167    * HandlerBase).
168    *
169    * Applications may register a new or different handler in the
170    * middle of a parse, and the SAX parser must begin using the new
171    * handler immediately.
172    *
173    * @param handler The document handler.
174    * @see DocumentHandler#DocumentHandler
175    * @see HandlerBase#HandlerBase
176    */
177    virtual void setDocumentHandler(DocumentHandler* const handler) = 0;
178
179  /**
180    * Allow an application to register an error event handler.
181    *
182    * If the application does not register an error event handler,
183    * all error events reported by the SAX parser will be silently
184    * ignored, except for fatalError, which will throw a SAXException
185    * (this is the default behaviour implemented by HandlerBase).
186    *
187    * Applications may register a new or different handler in the
188    * middle of a parse, and the SAX parser must begin using the new
189    * handler immediately.
190    *
191    * @param handler The error handler.
192    * @see ErrorHandler#ErrorHandler
193    * @see SAXException#SAXException
194    * @see HandlerBase#HandlerBase
195    */
196    virtual void setErrorHandler(ErrorHandler* const handler) = 0;
197
198  /**
199    * Parse an XML document.
200    *
201    * The application can use this method to instruct the SAX parser
202    * to begin parsing an XML document from any valid input
203    * source (a character stream, a byte stream, or a URI).
204    *
205    * Applications may not invoke this method while a parse is in
206    * progress (they should create a new Parser instead for each
207    * additional XML document).  Once a parse is complete, an
208    * application may reuse the same Parser object, possibly with a
209    * different input source.
210    *
211    * @param source The input source for the top-level of the
212    *               XML document.
213    * @exception SAXException Any SAX exception, possibly
214    *            wrapping another exception.
215    * @exception XMLException An exception from the parser or client
216    *            handler code.
217    * @see InputSource#InputSource
218    * @see #setEntityResolver
219    * @see #setDTDHandler
220    * @see #setDocumentHandler
221    * @see #setErrorHandler
222    */
223    virtual void parse
224    (
225        const   InputSource&    source
226    ) = 0;
227
228  /**
229    * Parse an XML document from a system identifier (URI).
230    *
231    * This method is a shortcut for the common case of reading a
232    * document from a system identifier.  It is the exact equivalent
233    * of the following:
234    *
235    * parse(new URLInputSource(systemId));
236    *
237    * If the system identifier is a URL, it must be fully resolved
238    * by the application before it is passed to the parser.
239    *
240    * @param systemId The system identifier (URI).
241    * @exception SAXException Any SAX exception, possibly
242    *            wrapping another exception.
243    * @exception XMLException An exception from the parser or client
244    *            handler code.
245    * @see #parse(InputSource)
246    */
247    virtual void parse
248    (
249        const   XMLCh* const    systemId
250    ) = 0;
251
252  /**
253    * Parse an XML document from a system identifier (URI).
254    *
255    * This method is a shortcut for the common case of reading a
256    * document from a system identifier.  It is the exact equivalent
257    * of the following:
258    *
259    * parse(new URLInputSource(systemId));
260    *
261    * If the system identifier is a URL, it must be fully resolved
262    * by the application before it is passed to the parser.
263    *
264    * @param systemId The system identifier (URI).
265    * @exception SAXException Any SAX exception, possibly
266    *            wrapping another exception.
267    * @exception XMLException An exception from the parser or client
268    *            handler code.
269    * @see #parse(InputSource)
270    */
271    virtual void parse
272    (
273        const   char* const     systemId
274    ) = 0;
275    //@}
276
277
278private :
279    /* The copy constructor, you cannot call this directly */
280    Parser(const Parser&);
281
282    /* The assignment operator, you cannot call this directly */
283    Parser& operator=(const Parser&);
284};
285
286XERCES_CPP_NAMESPACE_END
287
288#endif
Note: See TracBrowser for help on using the repository browser.