All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Reader.h
Go to the documentation of this file.
1 /* Copyright (C) 2001-2009 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 double.
292  */
293  virtual double getAttrAsDouble(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 i The attribute position.
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(std::size_t i) const;
305 
306  /*!
307  \brief It returns the local part of the attribute name for the i-th attribute.
308 
309  \param i The attribute position index.
310 
311  \return The local part of the attribute name in the case of an element node.
312  */
313  virtual std::string getAttrLocalName(std::size_t i) const = 0;
314 
315  /*!
316  \brief It returns the qualified name for the i-th attribute.
317 
318  \param i The attribute position index.
319 
320  \return The qualified attribute name in the case of an element node.
321  */
322  virtual std::string getAttrQName(std::size_t i) const = 0;
323 
324  /*!
325  \brief It returns the attribute URI of the associated namespace in the case of an element node.
326 
327  \param i The attribute position index.
328 
329  \return The attribute URI of the associated namespace in the case of an element node.
330  */
331  virtual std::string getAttrURI(std::size_t i) const = 0;
332 
333  /*!
334  \brief It returns the attribute position.
335 
336  \param name The attribute name.
337 
338  \return The attribute position.
339  */
340  virtual std::size_t getAttrPosition(const std::string& name) const = 0;
341 
342  virtual std::size_t getNumberOfNamespaces() const = 0;
343 
344  virtual void getNamespace(std::size_t i, std::pair<std::string, std::string>& ns) const = 0;
345 
346  /*!
347  \brief It sets the maximal allowed buffer size used for parsing.
348 
349  \param size The maximal allowed buffer size used for parsing.
350 
351  \note Default: 65536 bytes (64 kbytes), see the macro TE_XML_READER_MAX_BUFFSIZE.
352  \note The default value may be implementation dependent!
353  */
354  virtual void setInternalBufferSize(const std::size_t size) = 0;
355  };
356 
357  } // end namespace xml
358 } // end namespace te
359 
360 #endif // __TERRALIB_XML_INTERNAL_READER_H
361 
te::xml::Reader
This class models a XML reader object.
Definition: Reader.h:55
TEXMLEXPORT
#define TEXMLEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:119
te::xml::NodeType
NodeType
The type of node read by XML reader.
Definition: Enums.h:40
te::xml::Reader::Reader
Reader()
Default constructor.
Definition: Reader.h:60
Enums.h
Enumerations of XML module.
te::xml::Reader::~Reader
virtual ~Reader()
Virtual destructor.
Definition: Reader.h:63
Config.h
Configuration flags for the XML API of TerraLib.