source: icXML/icXML-devel/src/xercesc/sax/Parser.hpp @ 2722

Last change on this file since 2722 was 2722, checked in by cameron, 6 years ago

Original Xerces files with import mods for icxercesc

File size: 8.1 KB
Line 
1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *      http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/*
19 * $Id: Parser.hpp 527149 2007-04-10 14:56:39Z amassari $
20 */
21
22#if !defined(XERCESC_INCLUDE_GUARD_PARSER_HPP)
23#define XERCESC_INCLUDE_GUARD_PARSER_HPP
24
25#include <xercesc/util/XercesDefs.hpp>
26
27XERCES_CPP_NAMESPACE_BEGIN
28
29class DTDHandler;
30class EntityResolver;
31class DocumentHandler;
32class ErrorHandler;
33class InputSource;
34
35/**
36  * Basic interface for SAX (Simple API for XML) parsers.
37  *
38  * All SAX parsers must implement this basic interface: it allows
39  * applications to register handlers for different types of events
40  * and to initiate a parse from a URI, or a character stream.
41  *
42  * All SAX parsers must also implement a zero-argument constructor
43  * (though other constructors are also allowed).
44  *
45  * SAX parsers are reusable but not re-entrant: the application
46  * may reuse a parser object (possibly with a different input source)
47  * once the first parse has completed successfully, but it may not
48  * invoke the parse() methods recursively within a parse.
49  *
50  * @see EntityResolver#EntityResolver
51  * @see DTDHandler#DTDHandler
52  * @see DocumentHandler#DocumentHandler
53  * @see ErrorHandler#ErrorHandler
54  * @see HandlerBase#HandlerBase
55  * @see InputSource#InputSource
56  */
57
58#include <xercesc/util/XercesDefs.hpp>
59
60class SAX_EXPORT Parser
61{
62public:
63    /** @name Constructors and Destructor */
64    // -----------------------------------------------------------------------
65    //  Constructors and Destructor
66    // -----------------------------------------------------------------------
67    //@{
68    /** The default constructor */
69    Parser()
70    {
71    }
72    /** The destructor */
73    virtual ~Parser()
74    {
75    }
76    //@}
77
78    //-----------------------------------------------------------------------
79    // The parser interface
80    //-----------------------------------------------------------------------
81    /** @name The parser interfaces */
82    //@{
83  /**
84    * Allow an application to register a custom entity resolver.
85    *
86    * If the application does not register an entity resolver, the
87    * SAX parser will resolve system identifiers and open connections
88    * to entities itself (this is the default behaviour implemented in
89    * HandlerBase).
90    *
91    * Applications may register a new or different entity resolver
92    * in the middle of a parse, and the SAX parser must begin using
93    * the new resolver immediately.
94    *
95    * @param resolver The object for resolving entities.
96    * @see EntityResolver#EntityResolver
97    * @see HandlerBase#HandlerBase
98    */
99    virtual void setEntityResolver(EntityResolver* const resolver) = 0;
100
101  /**
102    * Allow an application to register a DTD event handler.
103    *
104    * If the application does not register a DTD handler, all DTD
105    * events reported by the SAX parser will be silently ignored (this
106    * is the default behaviour implemented by HandlerBase).
107    *
108    * Applications may register a new or different handler in the middle
109    * of a parse, and the SAX parser must begin using the new handler
110    * immediately.
111    *
112    * @param handler The DTD handler.
113    * @see DTDHandler#DTDHandler
114    * @see HandlerBase#HandlerBase
115    */
116    virtual void setDTDHandler(DTDHandler* const handler) = 0;
117
118  /**
119    * Allow an application to register a document event handler.
120    *
121    * If the application does not register a document handler, all
122    * document events reported by the SAX parser will be silently
123    * ignored (this is the default behaviour implemented by
124    * HandlerBase).
125    *
126    * Applications may register a new or different handler in the
127    * middle of a parse, and the SAX parser must begin using the new
128    * handler immediately.
129    *
130    * @param handler The document handler.
131    * @see DocumentHandler#DocumentHandler
132    * @see HandlerBase#HandlerBase
133    */
134    virtual void setDocumentHandler(DocumentHandler* const handler) = 0;
135
136  /**
137    * Allow an application to register an error event handler.
138    *
139    * If the application does not register an error event handler,
140    * all error events reported by the SAX parser will be silently
141    * ignored, except for fatalError, which will throw a SAXException
142    * (this is the default behaviour implemented by HandlerBase).
143    *
144    * Applications may register a new or different handler in the
145    * middle of a parse, and the SAX parser must begin using the new
146    * handler immediately.
147    *
148    * @param handler The error handler.
149    * @see ErrorHandler#ErrorHandler
150    * @see SAXException#SAXException
151    * @see HandlerBase#HandlerBase
152    */
153    virtual void setErrorHandler(ErrorHandler* const handler) = 0;
154
155  /**
156    * Parse an XML document.
157    *
158    * The application can use this method to instruct the SAX parser
159    * to begin parsing an XML document from any valid input
160    * source (a character stream, a byte stream, or a URI).
161    *
162    * Applications may not invoke this method while a parse is in
163    * progress (they should create a new Parser instead for each
164    * additional XML document).  Once a parse is complete, an
165    * application may reuse the same Parser object, possibly with a
166    * different input source.
167    *
168    * @param source The input source for the top-level of the
169    *               XML document.
170    * @exception SAXException Any SAX exception, possibly
171    *            wrapping another exception.
172    * @exception XMLException An exception from the parser or client
173    *            handler code.
174    * @see InputSource#InputSource
175    * @see #setEntityResolver
176    * @see #setDTDHandler
177    * @see #setDocumentHandler
178    * @see #setErrorHandler
179    */
180    virtual void parse
181    (
182        const   InputSource&    source
183    ) = 0;
184
185  /**
186    * Parse an XML document from a system identifier (URI).
187    *
188    * This method is a shortcut for the common case of reading a
189    * document from a system identifier.  It is the exact equivalent
190    * of the following:
191    *
192    * parse(new URLInputSource(systemId));
193    *
194    * If the system identifier is a URL, it must be fully resolved
195    * by the application before it is passed to the parser.
196    *
197    * @param systemId The system identifier (URI).
198    * @exception SAXException Any SAX exception, possibly
199    *            wrapping another exception.
200    * @exception XMLException An exception from the parser or client
201    *            handler code.
202    * @see #parse(const InputSource&)
203    */
204    virtual void parse
205    (
206        const   XMLCh* const    systemId
207    ) = 0;
208
209  /**
210    * Parse an XML document from a system identifier (URI).
211    *
212    * This method is a shortcut for the common case of reading a
213    * document from a system identifier.  It is the exact equivalent
214    * of the following:
215    *
216    * parse(new URLInputSource(systemId));
217    *
218    * If the system identifier is a URL, it must be fully resolved
219    * by the application before it is passed to the parser.
220    *
221    * @param systemId The system identifier (URI).
222    * @exception SAXException Any SAX exception, possibly
223    *            wrapping another exception.
224    * @exception XMLException An exception from the parser or client
225    *            handler code.
226    * @see #parse(const InputSource&)
227    */
228    virtual void parse
229    (
230        const   char* const     systemId
231    ) = 0;
232    //@}
233
234
235private :
236    /* The copy constructor, you cannot call this directly */
237    Parser(const Parser&);
238
239    /* The assignment operator, you cannot call this directly */
240    Parser& operator=(const Parser&);
241};
242
243XERCES_CPP_NAMESPACE_END
244
245#endif
Note: See TracBrowser for help on using the repository browser.