|
1 /* |
|
2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * |
|
16 */ |
|
17 /* |
|
18 * Licensed to the Apache Software Foundation (ASF) under one or more |
|
19 * contributor license agreements. See the NOTICE file distributed with |
|
20 * this work for additional information regarding copyright ownership. |
|
21 * The ASF licenses this file to You under the Apache License, Version 2.0 |
|
22 * (the "License"); you may not use this file except in compliance with |
|
23 * the License. You may obtain a copy of the License at |
|
24 * |
|
25 * http://www.apache.org/licenses/LICENSE-2.0 |
|
26 * |
|
27 * Unless required by applicable law or agreed to in writing, software |
|
28 * distributed under the License is distributed on an "AS IS" BASIS, |
|
29 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
|
30 * See the License for the specific language governing permissions and |
|
31 * limitations under the License. |
|
32 */ |
|
33 |
|
34 /* |
|
35 * $Id: XMLDocumentHandler.hpp 568078 2007-08-21 11:43:25Z amassari $ |
|
36 */ |
|
37 |
|
38 |
|
39 #if !defined(XMLDOCUMENTHANDLER_HPP) |
|
40 #define XMLDOCUMENTHANDLER_HPP |
|
41 |
|
42 #include <xercesc/util/XercesDefs.hpp> |
|
43 #include <xercesc/util/RefVectorOf.hpp> |
|
44 #include <xercesc/framework/XMLAttr.hpp> |
|
45 |
|
46 XERCES_CPP_NAMESPACE_BEGIN |
|
47 |
|
48 class XMLElementDecl; |
|
49 class XMLEntityDecl; |
|
50 |
|
51 /** |
|
52 * This abstract class provides the interface for the scanner to return |
|
53 * XML document information up to the parser as it scans through the |
|
54 * document. |
|
55 * |
|
56 * The interface is very similar to org.sax.DocumentHandler, but |
|
57 * has some extra methods required to get all the data out. |
|
58 */ |
|
59 class XMLPARSER_EXPORT XMLDocumentHandler |
|
60 { |
|
61 public: |
|
62 // ----------------------------------------------------------------------- |
|
63 // Constructors are hidden, just the virtual destructor is exposed |
|
64 // ----------------------------------------------------------------------- |
|
65 /** @name Destructor */ |
|
66 //@{ |
|
67 virtual ~XMLDocumentHandler() |
|
68 { |
|
69 } |
|
70 //@} |
|
71 |
|
72 /** @name The document handler interface */ |
|
73 //@{ |
|
74 /** Receive notification of character data. |
|
75 * |
|
76 * <p>The scanner will call this method to report each chunk of |
|
77 * character data. The scanner may return all contiguous character |
|
78 * data in a single chunk, or they may split it into several |
|
79 * chunks; however, all of the characters in any single event |
|
80 * will come from the same external entity, so that the Locator |
|
81 * provides useful information.</p> |
|
82 * |
|
83 * <p>The parser must not attempt to read from the array |
|
84 * outside of the specified range.</p> |
|
85 * |
|
86 * @param chars The content (characters) between markup from the XML |
|
87 * document. |
|
88 * @param length The number of characters to read from the array. |
|
89 * @param cdataSection Indicates that this data is inside a CDATA |
|
90 * section. |
|
91 * @see #ignorableWhitespace |
|
92 * @see Locator |
|
93 */ |
|
94 virtual void docCharacters |
|
95 ( |
|
96 const XMLCh* const chars |
|
97 , const unsigned int length |
|
98 , const bool cdataSection |
|
99 ) = 0; |
|
100 |
|
101 /** Receive notification of comments in the XML content being parsed. |
|
102 * |
|
103 * This scanner will call this method for any comments found in the |
|
104 * content of the document. |
|
105 * |
|
106 * @param comment The text of the comment. |
|
107 */ |
|
108 virtual void docComment |
|
109 ( |
|
110 const XMLCh* const comment |
|
111 ) = 0; |
|
112 |
|
113 /** Receive notification of PI's parsed in the XML content. |
|
114 * |
|
115 * The scanner will call this method for any PIs it finds within the |
|
116 * content of the document. |
|
117 * |
|
118 * @param target The name of the PI. |
|
119 * @param data The body of the PI. This may be an empty string since |
|
120 * the body is optional. |
|
121 */ |
|
122 virtual void docPI |
|
123 ( |
|
124 const XMLCh* const target |
|
125 , const XMLCh* const data |
|
126 ) = 0; |
|
127 |
|
128 /** Receive notification after the scanner has parsed the end of the |
|
129 * document. |
|
130 * |
|
131 * The scanner will call this method when the current document has been |
|
132 * fully parsed. The handler may use this opportunity to do something with |
|
133 * the data, clean up temporary data, etc... |
|
134 */ |
|
135 virtual void endDocument() = 0; |
|
136 |
|
137 /** Receive notification of the end of an element. |
|
138 * |
|
139 * This method is called when scanner encounters the end of element tag. |
|
140 * There will be a corresponding startElement() event for every |
|
141 * endElement() event, but not necessarily the other way around. For |
|
142 * empty tags, there is only a startElement() call. |
|
143 * |
|
144 * @param elemDecl The name of the element whose end tag was just |
|
145 * parsed. |
|
146 * @param uriId The ID of the URI in the URI pool (only valid if |
|
147 * name spaces is enabled) |
|
148 * @param isRoot Indicates if this is the root element. |
|
149 * @param prefixName The string representing the prefix name |
|
150 */ |
|
151 virtual void endElement |
|
152 ( |
|
153 const XMLElementDecl& elemDecl |
|
154 , const unsigned int uriId |
|
155 , const bool isRoot |
|
156 , const XMLCh* const prefixName = 0 |
|
157 ) = 0; |
|
158 |
|
159 /** Receive notification when a referenced entity's content ends |
|
160 * |
|
161 * This method is called when scanner encounters the end of an entity |
|
162 * reference. |
|
163 * |
|
164 * @param entDecl The name of the entity reference just scanned. |
|
165 */ |
|
166 virtual void endEntityReference |
|
167 ( |
|
168 const XMLEntityDecl& entDecl |
|
169 ) = 0; |
|
170 |
|
171 /** Receive notification of ignorable whitespace in element content. |
|
172 * |
|
173 * <p>Validating Parsers must use this method to report each chunk |
|
174 * of ignorable whitespace (see the W3C XML 1.0 recommendation, |
|
175 * section 2.10): non-validating parsers may also use this method |
|
176 * if they are capable of parsing and using content models.</p> |
|
177 * |
|
178 * <p>The scanner may return all contiguous whitespace in a single |
|
179 * chunk, or it may split it into several chunks; however, all of |
|
180 * the characters in any single event will come from the same |
|
181 * external entity, so that the Locator provides useful |
|
182 * information.</p> |
|
183 * |
|
184 * <p>The parser must not attempt to read from the array |
|
185 * outside of the specified range.</p> |
|
186 * |
|
187 * @param chars The whitespace characters from the XML document. |
|
188 * @param length The number of characters to read from the array. |
|
189 * @param cdataSection Indicates that this data is inside a CDATA |
|
190 * section. |
|
191 * @see #characters |
|
192 */ |
|
193 virtual void ignorableWhitespace |
|
194 ( |
|
195 const XMLCh* const chars |
|
196 , const unsigned int length |
|
197 , const bool cdataSection |
|
198 ) = 0; |
|
199 |
|
200 /** Reset the document handler's state, if required |
|
201 * |
|
202 * This method is used to give the registered document handler a |
|
203 * chance to reset itself. Its called by the scanner at the start of |
|
204 * every parse. |
|
205 */ |
|
206 virtual void resetDocument() = 0; |
|
207 |
|
208 /** Receive notification of the start of a new document |
|
209 * |
|
210 * This method is the first callback called the scanner at the |
|
211 * start of every parse. This is before any content is parsed. |
|
212 */ |
|
213 virtual void startDocument() = 0; |
|
214 |
|
215 /** Receive notification of a new start tag |
|
216 * |
|
217 * This method is called when scanner encounters the start of an element tag. |
|
218 * All elements must always have a startElement() tag. Empty tags will |
|
219 * only have the startElement() tag and no endElement() tag. |
|
220 * |
|
221 * @param elemDecl The name of the element whose start tag was just |
|
222 * parsed. |
|
223 * @param uriId The ID of the URI in the URI pool (only valid if |
|
224 * name spaces is enabled) |
|
225 * @param prefixName The string representing the prefix name |
|
226 * @param attrList List of attributes in the element |
|
227 * @param attrCount Count of the attributes in the element |
|
228 * @param isEmpty Indicates if the element is empty, in which case |
|
229 * you should not expect an endElement() event. |
|
230 * @param isRoot Indicates if this is the root element. |
|
231 */ |
|
232 virtual void startElement |
|
233 ( |
|
234 const XMLElementDecl& elemDecl |
|
235 , const unsigned int uriId |
|
236 , const XMLCh* const prefixName |
|
237 , const RefVectorOf<XMLAttr>& attrList |
|
238 , const unsigned int attrCount |
|
239 , const bool isEmpty |
|
240 , const bool isRoot |
|
241 ) = 0; |
|
242 |
|
243 /** Receive notification when the scanner hits an entity reference. |
|
244 * |
|
245 * This is currently useful only to DOM parser configurations as SAX |
|
246 * does not provide any api to return this information. |
|
247 * |
|
248 * @param entDecl The name of the entity that was referenced. |
|
249 */ |
|
250 virtual void startEntityReference(const XMLEntityDecl& entDecl) = 0; |
|
251 |
|
252 /** Receive notification of an XML declaration |
|
253 * |
|
254 * Currently neither DOM nor SAX provide API's to return back this |
|
255 * information. |
|
256 * |
|
257 * @param versionStr The value of the <code>version</code> pseudoattribute |
|
258 * of the XML decl. |
|
259 * @param encodingStr The value of the <code>encoding</code> pseudoattribute |
|
260 * of the XML decl. |
|
261 * @param standaloneStr The value of the <code>standalone</code> |
|
262 * pseudoattribute of the XML decl. |
|
263 * @param autoEncodingStr The encoding string auto-detected by the |
|
264 * scanner. In absence of any 'encoding' attribute in the |
|
265 * XML decl, the XML standard specifies how a parser can |
|
266 * auto-detect. If there is no <code>encodingStr</code> |
|
267 * this is what will be used to try to decode the file. |
|
268 */ |
|
269 virtual void XMLDecl |
|
270 ( |
|
271 const XMLCh* const versionStr |
|
272 , const XMLCh* const encodingStr |
|
273 , const XMLCh* const standaloneStr |
|
274 , const XMLCh* const autoEncodingStr |
|
275 ) = 0; |
|
276 |
|
277 /** Receive notification of the name and namespace of the type that validated |
|
278 * the element corresponding to the most recent endElement event. |
|
279 * This event will be fired immediately after the |
|
280 * endElement() event that signifies the end of the element |
|
281 * to which it applies; no other events will intervene. |
|
282 * This method is <em>EXPERIMENTAL</em> and may change, disappear |
|
283 * or become pure virtual at any time. |
|
284 * |
|
285 * This corresponds to a part of the information required by DOM Core |
|
286 * level 3's TypeInfo interface. |
|
287 * |
|
288 * @param typeName local name of the type that actually validated |
|
289 * the content of the element corresponding to the |
|
290 * most recent endElement() callback |
|
291 * @param typeURI namespace of the type that actually validated |
|
292 * the content of the element corresponding to the |
|
293 * most recent endElement() callback |
|
294 * @deprecated |
|
295 */ |
|
296 virtual void elementTypeInfo |
|
297 ( |
|
298 const XMLCh* const /* typeName */ |
|
299 , const XMLCh* const /* typeURI */ |
|
300 ) { /* non pure virtual to permit backward compatibility of implementations. */ }; |
|
301 //@} |
|
302 |
|
303 |
|
304 |
|
305 protected : |
|
306 // ----------------------------------------------------------------------- |
|
307 // Hidden Constructors |
|
308 // ----------------------------------------------------------------------- |
|
309 XMLDocumentHandler() |
|
310 { |
|
311 } |
|
312 |
|
313 |
|
314 private: |
|
315 // ----------------------------------------------------------------------- |
|
316 // Unimplemented constructors and operators |
|
317 // ----------------------------------------------------------------------- |
|
318 XMLDocumentHandler(const XMLDocumentHandler&); |
|
319 XMLDocumentHandler& operator=(const XMLDocumentHandler&); |
|
320 }; |
|
321 |
|
322 XERCES_CPP_NAMESPACE_END |
|
323 |
|
324 #endif |