Reader.h
Go to the documentation of this file.
1 /* Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
2 
3  This file is part of the TerraLib - a Framework for building GIS enabled applications.
4 
5  TerraLib is free software: you can redistribute it and/or modify
6  it under the terms of the GNU Lesser General Public License as published by
7  the Free Software Foundation, either version 3 of the License,
8  or (at your option) any later version.
9 
10  TerraLib is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU Lesser General Public License for more details.
14 
15  You should have received a copy of the GNU Lesser General Public License
16  along with TerraLib. See COPYING. If not, write to
17  TerraLib Team at <terralib-team@terralib.org>.
18  */
19 
20 /*!
21  \file terralib/xml/Reader.h
22 
23  \brief This class models a XML reader object.
24 */
25 
26 #ifndef __TERRALIB_XML_INTERNAL_READER_H
27 #define __TERRALIB_XML_INTERNAL_READER_H
28 
29 // TerraLib
30 #include "Config.h"
31 #include "Enums.h"
32 
33 // STL
34 #include <string>
35 
36 // Boost
37 #include <boost/cstdint.hpp>
38 #include <boost/noncopyable.hpp>
39 
40 namespace te
41 {
42  namespace xml
43  {
44  /*!
45  \class Reader
46 
47  \brief This class models a XML reader object.
48 
49  This API is intend to simplify the task of reading XML files. We have
50  tried to model it close to the Libxml2 API (see http://xmlsoft.org/xmlreader.html for more information)
51  but keeping all Xerces-C++ support capabilities: schema validation and grammar cache.
52 
53  \ingroup xml
54  */
55  class TEXMLEXPORT Reader : public boost::noncopyable
56  {
57  public:
58 
59  /*! \brief Default constructor. */
60  Reader() { }
61 
62  /*! \brief Virtual destructor. */
63  virtual ~Reader() { }
64 
65  /*!
66  \brief It enables or disables the parser namespace processing.
67 
68  \param d If true the internal parser will perform the namespace processing otherwise this will not be done.
69 
70  \note By default the reader is set to do namespace processing.
71  */
72  virtual void setDoNamespaces(bool d) = 0;
73 
74  /*!
75  \brief It enables or disables the parser schema processing.
76 
77  \param d If true the internal parser will perform the schema processing otherwise this will not be done.
78 
79  \note If set to true the namespace processing must also be turned on.
80 
81  \note By default the reader is set to parser schema.
82  */
83  virtual void setDoSchema(bool d) = 0;
84 
85  /*!
86  \brief If true the parser will perform a validation scheme.
87 
88  \param d If true the parser will perform a validation scheme.
89 
90  \note By default the reader is set to validate the scheme.
91  */
92  virtual void setValidationScheme(bool d) = 0;
93 
94  /*!
95  \brief If true the reader will use cached grammar if it exists in the pool.
96 
97  \param d If true the reader will use cached grammar if it exists in the pool.
98 
99  \note By default the reader is set to use cached grammar.
100  */
101  virtual void setUseCachedGrammarInParse(bool d) = 0;
102 
103  /*!
104  \brief If true it caches the grammar in the pool for re-use in subsequent parses.
105 
106  \param d If If true it caches the grammar in the pool for re-use in subsequent parses.
107 
108  \note By default the reader is set to cache the grammar.
109  */
110  virtual void setCacheGrammarFromParse(bool d) = 0;
111 
112  /*!
113  \brief If true the parser will ignore the white space characters.
114 
115  \param d If true the parser will ignore the white space characters.
116 
117  \note By default the reader is set to consider white spaces.
118  */
119  virtual void setIgnoreWhiteSpaces(bool d) = 0;
120 
121  /*!
122  \brief It prepare the given file to be read.
123 
124  You must call read to start parsing the XML document.
125 
126  \param fileURI A path to a XML file or any URI where it can be found.
127 
128  \exception Exception It throws an exception if the file doesn't exist or if the internal parser can not read it.
129  */
130  virtual void read(const std::string& fileURI) = 0;
131 
132  /*!
133  \brief It gets the next event to be read.
134 
135  \return True if an event was read otherwise false.
136 
137  \exception Exception It throws an exception if something goes wrong during the text read.
138  */
139  virtual bool next() = 0;
140 
141  /*!
142  \brief It return the type of node read.
143 
144  \return The type of node read.
145  */
146  virtual NodeType getNodeType() const = 0;
147 
148  /*!
149  \brief It returns the URI of the associated namespace in the case of an element node.
150 
151  \return The URI of the associated namespace in the case of an element node.
152  */
153  virtual std::string getElementURI() const = 0;
154 
155  /*!
156  \brief It returns the local part of the element name in the case of an element node.
157 
158  \return The local part of the element name in the case of an element node.
159  */
160  virtual std::string getElementLocalName() const = 0;
161 
162  /*!
163  \brief It returns the qualified name in the case of an element node.
164 
165  \return The qualified name in the case of an element node.
166  */
167  virtual std::string getElementQName() const = 0;
168 
169  /*!
170  \brief It returns the element data value in the case of VALUE node.
171 
172  \return The element data value in the case of VALUE node.
173  */
174  virtual std::string getElementValue() const = 0;
175 
176  /*!
177  \brief It returns the element data value in the case of VALUE node.
178 
179  \return The element data value in the case of VALUE node.
180 
181  \note Just call this method if you know that the element value can be converted to a 32-bit integer.
182  */
183  virtual boost::int32_t getElementValueAsInt32() const;
184 
185  /*!
186  \brief It returns the element data value in the case of VALUE node.
187 
188  \return The element data value in the case of VALUE node.
189 
190  \note Just call this method if you know that the element value can be converted to a double.
191  */
192  virtual double getElementValueAsDouble() const;
193 
194  /*!
195  \brief It returns the element data value in the case of VALUE node.
196 
197  \return The element data value in the case of VALUE node.
198 
199  \note Just call this method if you know that the element value can be converted to a boolean.
200  */
201  virtual bool getElementValueAsBoolean() const;
202 
203  /*!
204  \brief It returns the element data value in the case of VALUE node.
205 
206  \return The element data value in the case of VALUE node.
207 
208  \note Just call this method if you know that the element value can be converted to a bool.
209  */
210  //virtual bool getElementValueAsBool() const;
211 
212  /*!
213  \brief It returns the element data value length in the case of VALUE or CDATA node.
214 
215  \return The element data value in the case of VALUE or CDATA node.
216  */
217  virtual std::size_t getElementDataLen() const = 0;
218 
219  /*!
220  \brief It tells if the element has attributes in the case of an element node.
221 
222  \return True if the element has attributes in the case of an element node, otherwise, false.
223  */
224  virtual bool hasAttrs() const = 0;
225 
226  /*!
227  \brief It returns the number of attributes in the case of an element node.
228 
229  \return The number of attributes in the case of an element node.
230  */
231  virtual std::size_t getNumberOfAttrs() const = 0;
232 
233  /*!
234  \brief It returns the attribute value in the case of an element node with valid attributes.
235 
236  \param name The attribute name.
237 
238  \return The attribute value in the case of an element node with valid attributes.
239  */
240  virtual std::string getAttr(const std::string& name) const = 0;
241 
242  /*!
243  \brief It returns the attribute value in the case of an element node with valid attributes.
244 
245  \param i The attribute position.
246 
247  \return The attribute value in the case of an element node with valid attributes.
248  */
249  virtual std::string getAttr(std::size_t i) const = 0;
250 
251  /*!
252  \brief It returns the attribute value in the case of an element node with valid attributes.
253 
254  \param name The attribute name.
255 
256  \return The attribute value in the case of an element node with valid attributes.
257 
258  \note Just call this method if you know that the attribute value can be converted to a 32-bit integer.
259  */
260  virtual boost::int32_t getAttrAsInt32(const std::string& name) const;
261 
262  /*!
263  \brief It returns the attribute value in the case of an element node with valid attributes.
264 
265  \param i The attribute position.
266 
267  \return The attribute value in the case of an element node with valid attributes.
268 
269  \note Just call this method if you know that the attribute value can be converted to a 32-bit integer.
270  */
271  virtual boost::int32_t getAttrAsInt32(std::size_t i) const;
272 
273  /*!
274  \brief It returns the attribute value in the case of an element node with valid attributes.
275 
276  \param i The attribute position.
277 
278  \return The attribute value in the case of an element node with valid attributes.
279 
280  \note Just call this method if you know that the attribute value can be converted to a 32-bit unsigned integer.
281  */
282  virtual boost::uint32_t getAttrAsUInt32(std::size_t i) const;
283 
284  /*!
285  \brief It returns the attribute value in the case of an element node with valid attributes.
286 
287  \param name The attribute name.
288 
289  \return The attribute value in the case of an element node with valid attributes.
290 
291  \note Just call this method if you know that the attribute value can be converted to a 32-bit unsigned integer.
292  */
293  virtual boost::uint32_t getAttrAsUInt32(const std::string name) const;
294 
295  /*!
296  \brief It returns the attribute value in the case of an element node with valid attributes.
297 
298  \param name The attribute name.
299 
300  \return The attribute value in the case of an element node with valid attributes.
301 
302  \note Just call this method if you know that the attribute value can be converted to a double.
303  */
304  virtual double getAttrAsDouble(const std::string& name) const;
305 
306  /*!
307  \brief It returns the attribute value in the case of an element node with valid attributes.
308 
309  \param i The attribute position.
310 
311  \return The attribute value in the case of an element node with valid attributes.
312 
313  \note Just call this method if you know that the attribute value can be converted to a double.
314  */
315  virtual double getAttrAsDouble(std::size_t i) const;
316 
317  /*!
318  \brief It returns the local part of the attribute name for the i-th attribute.
319 
320  \param i The attribute position index.
321 
322  \return The local part of the attribute name in the case of an element node.
323  */
324  virtual std::string getAttrLocalName(std::size_t i) const = 0;
325 
326  /*!
327  \brief It returns the qualified name for the i-th attribute.
328 
329  \param i The attribute position index.
330 
331  \return The qualified attribute name in the case of an element node.
332  */
333  virtual std::string getAttrQName(std::size_t i) const = 0;
334 
335  /*!
336  \brief It returns the attribute URI of the associated namespace in the case of an element node.
337 
338  \param i The attribute position index.
339 
340  \return The attribute URI of the associated namespace in the case of an element node.
341  */
342  virtual std::string getAttrURI(std::size_t i) const = 0;
343 
344  /*!
345  \brief It returns the attribute position.
346 
347  \param name The attribute name.
348 
349  \return The attribute position.
350  */
351  virtual std::size_t getAttrPosition(const std::string& name) const = 0;
352 
353  virtual std::size_t getNumberOfNamespaces() const = 0;
354 
355  virtual void getNamespace(std::size_t i, std::pair<std::string, std::string>& ns) const = 0;
356 
357  /*!
358  \brief It sets the maximal allowed buffer size used for parsing.
359 
360  \param size The maximal allowed buffer size used for parsing.
361 
362  \note Default: 65536 bytes (64 kbytes), see the macro TE_XML_READER_MAX_BUFFSIZE.
363  \note The default value may be implementation dependent!
364  */
365  virtual void setInternalBufferSize(const std::size_t size) = 0;
366  };
367 
368  } // end namespace xml
369 } // end namespace te
370 
371 #endif // __TERRALIB_XML_INTERNAL_READER_H
372 
te::xml::Reader::~Reader
virtual ~Reader()
Virtual destructor.
Definition: Reader.h:63
te::xml::Reader
This class models a XML reader object.
Definition: Reader.h:55
te::xml::Reader::Reader
Reader()
Default constructor.
Definition: Reader.h:60
te::xml::NodeType
NodeType
The type of node read by XML reader.
Definition: Enums.h:40
Config.h
Configuration flags for the XML API of TerraLib.
te
URI C++ Library.
Definition: AddressGeocodingOp.h:51
Enums.h
Enumerations of XML module.
TEXMLEXPORT
#define TEXMLEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:88