source: icXML/icXML-devel/src/icxercesc/framework/XMLDocumentHandler.hpp @ 3157

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

Fixes for icXML 0.9

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