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

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

xerces added

Line 
1/*
2 * Copyright 1999-2000,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: DocumentHandler.hpp,v $
19 * Revision 1.4  2004/09/08 13:56:19  peiyongz
20 * Apache License Version 2.0
21 *
22 * Revision 1.3  2003/03/07 18:10:06  tng
23 * Return a reference instead of void for operator=
24 *
25 * Revision 1.2  2002/11/04 14:56:25  tng
26 * C++ Namespace Support.
27 *
28 * Revision 1.1.1.1  2002/02/01 22:22:08  peiyongz
29 * sane_include
30 *
31 * Revision 1.6  2000/03/02 19:54:34  roddey
32 * This checkin includes many changes done while waiting for the
33 * 1.1.0 code to be finished. I can't list them all here, but a list is
34 * available elsewhere.
35 *
36 * Revision 1.5  2000/02/24 20:12:55  abagchi
37 * Swat for removing Log from API docs
38 *
39 * Revision 1.4  2000/02/12 03:31:55  rahulj
40 * Removed duplicate CVS Log entries.
41 *
42 * Revision 1.3  2000/02/12 01:27:19  aruna1
43 * Documentation updated
44 *
45 * Revision 1.2  2000/02/06 07:47:57  rahulj
46 * Year 2K copyright swat.
47 *
48 * Revision 1.1.1.1  1999/11/09 01:07:43  twl
49 * Initial checkin
50 *
51 * Revision 1.2  1999/11/08 20:44:54  rahul
52 * Swat for adding in Product name and CVS comment log variable.
53 *
54 */
55
56
57#ifndef DOCUMENTHANDLER_HPP
58#define DOCUMENTHANDLER_HPP
59
60#include <xercesc/util/XercesDefs.hpp>
61
62XERCES_CPP_NAMESPACE_BEGIN
63
64class AttributeList;
65class Locator;
66
67/**
68  * Receive notification of general document events.
69  *
70  * <p>This is the main interface that most SAX applications
71  * implement: if the application needs to be informed of basic parsing
72  * events, it implements this interface and registers an instance with
73  * the SAX parser using the setDocumentHandler method.  The parser
74  * uses the instance to report basic document-related events like
75  * the start and end of elements and character data.</p>
76  *
77  * <p>The order of events in this interface is very important, and
78  * mirrors the order of information in the document itself.  For
79  * example, all of an element's content (character data, processing
80  * instructions, and/or subelements) will appear, in order, between
81  * the startElement event and the corresponding endElement event.</p>
82  *
83  * <p>Application writers who do not want to implement the entire
84  * interface while can derive a class from HandlerBase, which implements
85  * the default functionality; parser writers can instantiate
86  * HandlerBase to obtain a default handler.  The application can find
87  * the location of any document event using the Locator interface
88  * supplied by the Parser through the setDocumentLocator method.</p>
89  *
90  * @see Parser#setDocumentHandler
91  * @see Locator#Locator
92  * @see HandlerBase#HandlerBase
93  */
94
95class SAX_EXPORT DocumentHandler
96{
97public:
98    /** @name Constructors and Destructor */
99    //@{
100    /** Default constructor */
101    DocumentHandler()
102    {
103    }
104
105    /** Destructor */
106    virtual ~DocumentHandler()
107    {
108    }
109    //@}
110
111    /** @name The virtual document handler interface */
112
113    //@{
114   /**
115    * Receive notification of character data.
116    *
117    * <p>The Parser will call this method to report each chunk of
118    * character data.  SAX parsers may return all contiguous character
119    * data in a single chunk, or they may split it into several
120    * chunks; however, all of the characters in any single event
121    * must come from the same external entity, so that the Locator
122    * provides useful information.</p>
123    *
124    * <p>The application must not attempt to read from the array
125    * outside of the specified range.</p>
126    *
127    * <p>Note that some parsers will report whitespace using the
128    * ignorableWhitespace() method rather than this one (validating
129    * parsers must do so).</p>
130    *
131    * @param chars The characters from the XML document.
132    * @param length The number of characters to read from the array.
133    * @exception SAXException Any SAX exception, possibly
134    *            wrapping another exception.
135    * @see #ignorableWhitespace
136    * @see Locator#Locator
137    */
138    virtual void characters
139    (
140        const   XMLCh* const    chars
141        , const unsigned int    length
142    ) = 0;
143
144  /**
145    * Receive notification of the end of a document.
146    *
147    * <p>The SAX parser will invoke this method only once, and it will
148    * be the last method invoked during the parse.  The parser shall
149    * not invoke this method until it has either abandoned parsing
150    * (because of an unrecoverable error) or reached the end of
151    * input.</p>
152    *
153    * @exception SAXException Any SAX exception, possibly
154    *            wrapping another exception.
155    */
156    virtual void endDocument () = 0;
157
158  /**
159    * Receive notification of the end of an element.
160    *
161    * <p>The SAX parser will invoke this method at the end of every
162    * element in the XML document; there will be a corresponding
163    * startElement() event for every endElement() event (even when the
164    * element is empty).</p>
165    *
166    * <p>If the element name has a namespace prefix, the prefix will
167    * still be attached to the name.</p>
168    *
169    * @param name The element type name
170    * @exception SAXException Any SAX exception, possibly
171    *            wrapping another exception.
172    */
173    virtual void endElement(const XMLCh* const name) = 0;
174
175  /**
176    * Receive notification of ignorable whitespace in element content.
177    *
178    * <p>Validating Parsers must use this method to report each chunk
179    * of ignorable whitespace (see the W3C XML 1.0 recommendation,
180    * section 2.10): non-validating parsers may also use this method
181    * if they are capable of parsing and using content models.</p>
182    *
183    * <p>SAX parsers may return all contiguous whitespace in a single
184    * chunk, or they may split it into several chunks; however, all of
185    * the characters in any single event must come from the same
186    * external entity, so that the Locator provides useful
187    * information.</p>
188    *
189    * <p>The application must not attempt to read from the array
190    * outside of the specified range.</p>
191    *
192    * @param chars The characters from the XML document.
193    * @param length The number of characters to read from the array.
194    * @exception SAXException Any SAX exception, possibly
195    *            wrapping another exception.
196    * @see #characters
197    */
198    virtual void ignorableWhitespace
199    (
200        const   XMLCh* const    chars
201        , const unsigned int    length
202    ) = 0;
203
204  /**
205    * Receive notification of a processing instruction.
206    *
207    * <p>The Parser will invoke this method once for each processing
208    * instruction found: note that processing instructions may occur
209    * before or after the main document element.</p>
210    *
211    * <p>A SAX parser should never report an XML declaration (XML 1.0,
212    * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
213    * using this method.</p>
214    *
215    * @param target The processing instruction target.
216    * @param data The processing instruction data, or null if
217    *        none was supplied.
218    * @exception SAXException Any SAX exception, possibly
219    *            wrapping another exception.
220    */
221    virtual void processingInstruction
222    (
223        const   XMLCh* const    target
224        , const XMLCh* const    data
225    ) = 0;
226
227    /**
228    * Reset the Docuemnt object on its reuse
229    *
230    * <p>This method helps in reseting the document implementational
231    * defaults each time the document is begun.</p>
232    *
233    */
234    virtual void resetDocument() = 0;
235
236  /**
237    * Receive an object for locating the origin of SAX document events.
238    *
239    * SAX parsers are strongly encouraged (though not absolutely
240    * required) to supply a locator: if it does so, it must supply
241    * the locator to the application by invoking this method before
242    * invoking any of the other methods in the DocumentHandler
243    * interface.
244    *
245    * The locator allows the application to determine the end
246    * position of any document-related event, even if the parser is
247    * not reporting an error.  Typically, the application will
248    * use this information for reporting its own errors (such as
249    * character content that does not match an application's
250    * business rules). The information returned by the locator
251    * is probably not sufficient for use with a search engine.
252    *
253    * Note that the locator will return correct information only
254    * during the invocation of the events in this interface. The
255    * application should not attempt to use it at any other time.
256    *
257    * @param locator An object that can return the location of
258    *                any SAX document event. The object is only
259    *                'on loan' to the client code and they are not
260    *                to attempt to delete or modify it in any way!
261    *
262    * @see Locator#Locator
263    */
264    virtual void setDocumentLocator(const Locator* const locator) = 0;
265
266  /**
267    * Receive notification of the beginning of a document.
268    *
269    * <p>The SAX parser will invoke this method only once, before any
270    * other methods in this interface or in DTDHandler (except for
271    * setDocumentLocator).</p>
272    *
273    * @exception SAXException Any SAX exception, possibly
274    *            wrapping another exception.
275    */
276    virtual void startDocument() = 0;
277
278  /**
279    * Receive notification of the beginning of an element.
280    *
281    * <p>The Parser will invoke this method at the beginning of every
282    * element in the XML document; there will be a corresponding
283    * endElement() event for every startElement() event (even when the
284    * element is empty). All of the element's content will be
285    * reported, in order, before the corresponding endElement()
286    * event.</p>
287    *
288    * <p>If the element name has a namespace prefix, the prefix will
289    * still be attached.  Note that the attribute list provided will
290    * contain only attributes with explicit values (specified or
291    * defaulted): #IMPLIED attributes will be omitted.</p>
292    *
293    * @param name The element type name.
294    * @param attrs The attributes attached to the element, if any.
295    * @exception SAXException Any SAX exception, possibly
296    *            wrapping another exception.
297    * @see #endElement
298    * @see AttributeList#AttributeList
299    */
300    virtual void startElement
301    (
302        const   XMLCh* const    name
303        ,       AttributeList&  attrs
304    ) = 0;
305
306    //@}
307
308private :
309    /* Unimplemented Constructors and operators */
310    /* Copy constructor */
311    DocumentHandler(const DocumentHandler&);
312    /** Assignment operator */
313    DocumentHandler& operator=(const DocumentHandler&);
314};
315
316XERCES_CPP_NAMESPACE_END
317
318#endif
Note: See TracBrowser for help on using the repository browser.