source: icXML/icXML-devel/src/xercesc/framework/XMLDocumentHandler.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: 10.6 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: XMLDocumentHandler.hpp 673679 2008-07-03 13:50:10Z borisk $
20 */
21
22#if !defined(XERCESC_INCLUDE_GUARD_XMLDOCUMENTHANDLER_HPP)
23#define XERCESC_INCLUDE_GUARD_XMLDOCUMENTHANDLER_HPP
24
25#include <xercesc/util/XercesDefs.hpp>
26#include <xercesc/util/RefVectorOf.hpp>
27#include <icxercesc/framework/XMLAttr.hpp>
28
29XERCES_CPP_NAMESPACE_BEGIN
30
31class XMLElementDecl;
32class XMLEntityDecl;
33
34/**
35  * This abstract class provides the interface for the scanner to return
36  * XML document information up to the parser as it scans through the
37  * document.
38  *
39  * The interface is very similar to org.sax.DocumentHandler, but
40  * has some extra methods required to get all the data out.
41  */
42class XMLPARSER_EXPORT XMLDocumentHandler
43{
44public:
45    // -----------------------------------------------------------------------
46    //  Constructors are hidden, just the virtual destructor is exposed
47    // -----------------------------------------------------------------------
48    /** @name Destructor */
49    //@{
50    virtual ~XMLDocumentHandler()
51    {
52    }
53    //@}
54
55    /** @name The document handler interface */
56    //@{
57    /** Receive notification of character data.
58      *
59      * <p>The scanner will call this method to report each chunk of
60      * character data. The scanner may return all contiguous character
61      * data in a single chunk, or they may split it into several
62      * chunks; however, all of the characters in any single event
63      * will come from the same external entity, so that the Locator
64      * provides useful information.</p>
65      *
66      * <p>The parser must not attempt to read from the array
67      * outside of the specified range.</p>
68      *
69      * @param  chars           The content (characters) between markup from the XML
70      *                         document.
71      * @param  length          The number of characters to read from the array.
72      * @param  cdataSection    Indicates that this data is inside a CDATA
73      *                         section.
74      * @see #ignorableWhitespace
75      * @see Locator
76      */
77    virtual void docCharacters
78    (
79        const   XMLCh* const    chars
80        , const XMLSize_t       length
81        , const bool            cdataSection
82    ) = 0;
83
84    /** Receive notification of comments in the XML content being parsed.
85      *
86      * This scanner will call this method for any comments found in the
87      * content of the document.
88      *
89      * @param comment The text of the comment.
90      */
91    virtual void docComment
92    (
93        const   XMLCh* const    comment
94    ) = 0;
95
96    /** Receive notification of PI's parsed in the XML content.
97      *
98      * The scanner will call this method for any PIs it finds within the
99      * content of the document.
100      *
101      * @param  target  The name of the PI.
102      * @param  data    The body of the PI. This may be an empty string since
103      *                 the body is optional.
104      */
105    virtual void docPI
106    (
107        const   XMLCh* const    target
108        , const XMLCh* const    data
109    ) = 0;
110
111    /** Receive notification after the scanner has parsed the end of the
112      * document.
113      *
114      * The scanner will call this method when the current document has been
115      * fully parsed. The handler may use this opportunity to do something with
116      * the data, clean up temporary data, etc...
117      */
118    virtual void endDocument() = 0;
119
120    /** Receive notification of the end of an element.
121      *
122      * This method is called when scanner encounters the end of element tag.
123      * There will be a corresponding startElement() event for every
124      * endElement() event, but not necessarily the other way around. For
125      * empty tags, there is only a startElement() call.
126      *
127      * @param  elemDecl The name of the element whose end tag was just
128      *                     parsed.
129      * @param  uriId       The ID of the URI in the URI pool (only valid if
130      *                     name spaces is enabled)
131      * @param  isRoot      Indicates if this is the root element.
132      * @param  prefixName  The string representing the prefix name
133      */
134    virtual void endElement
135    (
136        const   XMLElementDecl& elemDecl
137        , const unsigned int    uriId
138        , const bool            isRoot
139        , const XMLCh* const    prefixName = 0
140    ) = 0;
141
142    /** Receive notification when a referenced entity's content ends
143      *
144      * This method is called when scanner encounters the end of an entity
145      * reference.
146      *
147      * @param  entDecl  The name of the entity reference just scanned.
148      */
149    virtual void endEntityReference
150    (
151        const   XMLEntityDecl&  entDecl
152    ) = 0;
153
154    /** Receive notification of ignorable whitespace in element content.
155      *
156      * <p>Validating Parsers must use this method to report each chunk
157      * of ignorable whitespace (see the W3C XML 1.0 recommendation,
158      * section 2.10): non-validating parsers may also use this method
159      * if they are capable of parsing and using content models.</p>
160      *
161      * <p>The scanner may return all contiguous whitespace in a single
162      * chunk, or it may split it into several chunks; however, all of
163      * the characters in any single event will come from the same
164      * external entity, so that the Locator provides useful
165      * information.</p>
166      *
167      * <p>The parser must not attempt to read from the array
168      * outside of the specified range.</p>
169      *
170      * @param  chars       The whitespace characters from the XML document.
171      * @param  length      The number of characters to read from the array.
172      * @param  cdataSection Indicates that this data is inside a CDATA
173      *                     section.
174      * @see #docCharacters
175      */
176    virtual void ignorableWhitespace
177    (
178        const   XMLCh* const    chars
179        , const XMLSize_t       length
180        , const bool            cdataSection
181    ) = 0;
182
183    /** Reset the document handler's state, if required
184      *
185      * This method is used to give the registered document handler a
186      * chance to reset itself. Its called by the scanner at the start of
187      * every parse.
188      */
189    virtual void resetDocument() = 0;
190
191    /** Receive notification of the start of a new document
192      *
193      * This method is the first callback called the scanner at the
194      * start of every parse. This is before any content is parsed.
195      */
196    virtual void startDocument() = 0;
197
198    /** Receive notification of a new start tag
199      *
200      * This method is called when scanner encounters the start of an element tag.
201      * All elements must always have a startElement() tag. Empty tags will
202      * only have the startElement() tag and no endElement() tag.
203      *
204      * @param  elemDecl The name of the element whose start tag was just
205      *                     parsed.
206      * @param  uriId       The ID of the URI in the URI pool (only valid if
207      *                     name spaces is enabled)
208      * @param  prefixName  The string representing the prefix name
209      * @param  attrList    List of attributes in the element
210      * @param  attrCount   Count of the attributes in the element
211      * @param  isEmpty     Indicates if the element is empty, in which case
212      *                     you should not expect an endElement() event.
213      * @param  isRoot      Indicates if this is the root element.
214      */
215    virtual void startElement
216    (
217        const   XMLElementDecl&         elemDecl
218        , const unsigned int            uriId
219        , const XMLCh* const            prefixName
220        , const RefVectorOf<XMLAttr>&   attrList
221        , const XMLSize_t               attrCount
222        , const bool                    isEmpty
223        , const bool                    isRoot
224    ) = 0;
225
226    /** Receive notification when the scanner hits an entity reference.
227      *
228      * This is currently useful only to DOM parser configurations as SAX
229      * does not provide any api to return this information.
230      *
231      * @param  entDecl  The name of the entity that was referenced.
232      */
233    virtual void startEntityReference(const XMLEntityDecl& entDecl) = 0;
234
235    /** Receive notification of an XML declaration
236      *
237      * Currently neither DOM nor SAX provide API's to return back this
238      * information.
239      *
240      * @param  versionStr      The value of the <code>version</code> pseudoattribute
241      *                         of the XML decl.
242      * @param  encodingStr     The value of the <code>encoding</code> pseudoattribute
243      *                         of the XML decl.
244      * @param  standaloneStr   The value of the <code>standalone</code>
245      *                         pseudoattribute of the XML decl.
246      * @param  autoEncodingStr The encoding string auto-detected by the
247      *                         scanner. In absence of any 'encoding' attribute in the
248      *                         XML decl, the XML standard specifies how a parser can
249      *                         auto-detect. If there is no <code>encodingStr</code>
250      *                         this is what will be used to try to decode the file.
251      */
252    virtual void XMLDecl
253    (
254        const   XMLCh* const    versionStr
255        , const XMLCh* const    encodingStr
256        , const XMLCh* const    standaloneStr
257        , const XMLCh* const    autoEncodingStr
258    ) = 0;
259
260    //@}
261
262
263
264protected :
265    // -----------------------------------------------------------------------
266    //  Hidden Constructors
267    // -----------------------------------------------------------------------
268    XMLDocumentHandler()
269    {
270    }
271
272
273private:
274    // -----------------------------------------------------------------------
275    //  Unimplemented constructors and operators
276    // -----------------------------------------------------------------------
277    XMLDocumentHandler(const XMLDocumentHandler&);
278    XMLDocumentHandler& operator=(const XMLDocumentHandler&);
279};
280
281XERCES_CPP_NAMESPACE_END
282
283#endif
Note: See TracBrowser for help on using the repository browser.