DataSet.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/dataaccess/dataset/DataSet.h
22 
23  \brief A dataset is the unit of information manipulated by the data access module of TerraLib.
24 */
25 
26 #ifndef __TERRALIB_DATAACCESS_INTERNAL_DATASET_H
27 #define __TERRALIB_DATAACCESS_INTERNAL_DATASET_H
28 
29 // TerraLib
30 #include "../../common/Enums.h"
31 #include "../../core/encoding/CharEncoding.h"
32 #include "../../datatype/Array.h"
33 #include "../../datatype/ByteArray.h"
34 #include "../../datatype/DateTime.h"
35 #include "../../datatype/Enums.h"
36 #include "../../geometry/Enums.h"
37 #include "../../raster/Raster.h"
38 #include "../Config.h"
39 
40 // STL
41 #include <string>
42 
43 // Boost
44 #include <boost/cstdint.hpp>
45 #include <boost/noncopyable.hpp>
46 #include <boost/shared_ptr.hpp>
47 
48 namespace te
49 {
50 // Forward declarations
51  namespace dt
52  {
53  class AbstractData;
54  }
55 
56 // Forward declarations
57  namespace gm
58  {
59  class Envelope;
60  class Geometry;
61  }
62 
63  namespace da
64  {
65 // Forward declarations
66  class DataSetItem;
67  class DataSourceTransactor;
68 
69  /*!
70  \class DataSet
71 
72  \brief A dataset is the unit of information manipulated by the data access module of TerraLib.
73 
74  A dataset is a container for a data collection with an internal pointer
75  pointing to a specific item in the collection. There are move methods
76  that can be used to set the position of this internal pointer.
77 
78  When the dataset is created, its internal pointer
79  points to a sentinel location before the first item
80  of the collection. So, in order to retrieve data
81  from this collection one of the move methods must be called before.
82 
83  Each item of the dataset is composed by any
84  number of properties. You have special methods to
85  query the property information (name, data type, constraints).
86 
87  The individual value of a property of an item in the collection,
88  can be retrieved by an appropriated get method. These methods
89  retrieve the value by an integer index identifying the property position or
90  by a string with the property name.
91 
92  When the dataset is the result of a query involving several
93  datasets, you can find out the dataset that gave the original
94  dataset name of a specific property.
95 
96  A dataset can be connected or disconnected. A connected dataset, after its creation through
97  the data source transactor, continues to depend on the connection given by its associated
98  data source. Differently, a disconnected dataset, after its creation, no more depends of the
99  connection given by the data source, and it continues to live after the connection has been
100  released to the data source.
101 
102  \ingroup dataaccess
103 
104  \sa DataSource, DataSourceTransactor, DataSetType
105 
106  \todo We can generalize the dataset API so that a dataset may contain other datasets;
107  in this case, it will be a collection of datasets.
108 
109  \note A geometric or raster property is represented just like any other data type.
110 
111  \note Our design also allows a dataset to have multiple geometric or raster properties.
112  */
113  class TEDATAACCESSEXPORT DataSet : public boost::noncopyable
114  {
115  public:
116 
117  /*! \brief Default constructor. */
118  DataSet() {}
119 
120  /*! \brief Virtual destructor. */
121  virtual ~DataSet() {}
122 
123  /** @name DataSet Methods
124  * Methods for obtaining information about a given dataset.
125  */
126  //@{
127 
128  /*!
129  \brief It returns the traverse type associated to the dataset.
130 
131  \return The traverse type associated to the dataset.
132  */
133  virtual te::common::TraverseType getTraverseType() const = 0;
134 
135  /*!
136  \brief It returns the read and write permission associated to the dataset.
137 
138  \return The read and write permission associated to the dataset.
139  */
140  virtual te::common::AccessPolicy getAccessPolicy() const = 0;
141 
142  /*!
143  \brief It returns the number of properties that composes an item of the dataset.
144 
145  \return The number of properties that composes an item of the dataset.
146  */
147  virtual std::size_t getNumProperties() const = 0;
148 
149  /*!
150  \brief It returns the underlying data type of the property at position pos.
151 
152  \param i The property position of interest.
153 
154  \return The underlying data type of the property at position pos.
155  */
156  virtual int getPropertyDataType(std::size_t i) const = 0;
157 
158  /*!
159  \brief It returns the property name at position pos.
160 
161  \param i The property name at the position of interest.
162 
163  \return The property name at position pos.
164  */
165  virtual std::string getPropertyName(std::size_t i) const = 0;
166 
167  /*!
168  \brief It returns the underlying dataset name of the property at position pos.
169 
170  \param i The property position of interest.
171 
172  \return The underlying dataset name of the property at position pos.
173  */
174  virtual std::string getDatasetNameOfProperty(std::size_t i) const = 0;
175  //@}
176 
177  /** @name Collection Methods
178  * Methods for getting/setting atomic datasets.
179  */
180  //@{
181 
182  /*!
183  \brief It returns true if the collection is empty.
184 
185  \return True, if the collection is empty.
186  */
187  virtual bool isEmpty() const = 0;
188 
189  /*!
190  \brief It returns true if the dataset is connected and false if it is disconnected.
191  A dataset can be connected or disconnected. A connected dataset, after its creation through
192  the data source transactor, continues to depend on the connection given by its associated
193  data source. Differently, a disconnected dataset, after its creation, no more depends of the
194  connection given by the data source, and it continues to live after the connection has been
195  released to the data source.
196 
197  \return True, if the dataset is connected, or false if it is disconnected.
198  */
199  virtual bool isConnected() const = 0;
200 
201  /*!
202  \brief It returns the collection size, if it is known.
203 
204  It may return std::string::npos if the size is not known,
205  or it would be too costly to compute it.
206 
207  \return The size of the collection, if it is known.
208  */
209  virtual std::size_t size() const = 0;
210 
211  /*!
212  \brief It computes the bounding rectangle for a spatial property of the dataset.
213 
214  \param i The position of a spatial property to get its bounding box.
215 
216  \pre The position i must be associated to a spatial property of the dataset.
217 
218  \exception Exception It throws an exception if something goes wrong during MBR search.
219 
220  \return The spatial property bounding rectangle, or an invalid box, if none is found.
221  */
222  virtual std::unique_ptr<te::gm::Envelope> getExtent(std::size_t i) = 0;
223 
224  /*!
225  \brief It moves the internal pointer to the next item of the collection.
226 
227  You always has to call this method in order to move the internal pointer to the first
228  item in the collection. This method can be used to traverse a dataset.
229 
230  \return True if the internal pointer is on a valid item, or false otherwise.
231 
232  \note All dataset types support this method: FORWARDONLY, BIDIRECTIONAL and RANDOM.
233  */
234  virtual bool moveNext() = 0;
235 
236  /*!
237  \brief It moves the internal pointer to the previous item of the collection.
238 
239  \return True, if the internal pointer (cursor position) is on a valid item, or false otherwise.
240 
241  \note This method is not supported by FORWARDONLY datasets.
242  */
243  virtual bool movePrevious() = 0;
244 
245  /*!
246  \brief It moves the internal pointer to a position before the first item in the collection.
247 
248  \return True, if it was possible to move to a sentinel position before the first item in the collection.
249 
250  \note This method is not supported by FORWARDONLY datasets.
251  */
252  virtual bool moveBeforeFirst() = 0;
253 
254  /*!
255  \brief It moves the internal pointer to the first item in the collection.
256 
257  \return True, if it was possible to move to the first item in the collection.
258 
259  \note This method is not supported by FORWARDONLY datasets.
260  */
261  virtual bool moveFirst() = 0;
262 
263  /*!
264  \brief It sets the dataset internal pointer to the last item in the collection.
265 
266  \return True, if it was possible to move to the last item in the collection.
267  */
268  virtual bool moveLast() = 0;
269 
270  /*!
271  \brief It moves the dataset internal pointer to a given position.
272 
273  \param i The position the dataset internal pointer must be set up.
274 
275  \return True, if it was possible to move the dataset reading to the given position.
276 
277  \note The first item in the collection starts at address 0.
278  */
279  virtual bool move(std::size_t i) = 0;
280 
281  /*!
282  \brief It tells if the dataset internal pointer is on the first element of the collection or not.
283 
284  \return True if the dataset internal pointer is on the first element otherwise it returns false.
285  */
286  virtual bool isAtBegin() const = 0;
287 
288  /*!
289  \brief It tells if the dataset internal pointer is in a position before the first element of the collection or not.
290 
291  \return True, if the dataset internal pointer is in a position before the first element otherwise it returns false.
292  */
293  virtual bool isBeforeBegin() const = 0;
294 
295  /*!
296  \brief It tells if the dataset internal pointer is on the last element of the collection.
297 
298  \return True, if the dataset internal pointer is on the last element otherwise it returns false.
299  */
300  virtual bool isAtEnd() const = 0;
301 
302  /*!
303  \brief It tells if the dataset internal pointer is on the sentinel position after the last element of the collection or not.
304 
305  \return True, if the dataset internal pointer is on the sentinel position after the last element otherwise it returns false.
306  */
307  virtual bool isAfterEnd() const = 0;
308 
309  /*!
310  \brief It tells if the dataset internal pointer is on a valid position.
311 
312  \return True, if the dataset internal pointer is on a valid position.
313  */
314  virtual bool isPositionValid() const = 0;
315 
316  //@}
317 
318  /** @name DataSet Element Properties
319  * Methods for retrieving/setting the dataset item component values without the need to explicitly instantiate an item via getItem method.
320  */
321  //@{
322 
323  /*!
324  \brief Method for retrieving a signed character attribute value (1 byte long).
325 
326  \param i The attribute index.
327 
328  \return The signed character attribute value (1 byte long) in the given position.
329  */
330  virtual char getChar(std::size_t i) const = 0;
331 
332  /*!
333  \brief Method for retrieving a signed character attribute value (1 byte long).
334 
335  \param name The attribute name.
336 
337  \return The signed character attribute value (1 byte long) with the given name.
338  */
339  virtual char getChar(const std::string& name) const;
340 
341  /*!
342  \brief Method for retrieving an unsigned character attribute value (1 byte long).
343 
344  \param i The attribute index.
345 
346  \return The unsigned character attribute value (1 byte long) in the given position.
347  */
348  virtual unsigned char getUChar(std::size_t i) const = 0;
349 
350  /*!
351  \brief Method for retrieving an unsigned character attribute value (1 byte long).
352 
353  \param name The attribute name.
354 
355  \return The unsigned character attribute value (1 byte long) with the given name.
356  */
357  virtual unsigned char getUChar(const std::string& name) const;
358 
359  /*!
360  \brief Method for retrieving a 16-bit integer attribute value (2 bytes long).
361 
362  \param i The attribute index.
363 
364  \return The 16-bit integer attribute value (2 bytes long) in the given position.
365  */
366  virtual boost::int16_t getInt16(std::size_t i) const = 0;
367 
368  /*!
369  \brief Method for retrieving a 16-bit integer attribute value (2 bytes long).
370 
371  \param name The attribute name.
372 
373  \return The 16-bit integer attribute value (2 bytes long) with the given name.
374  */
375  virtual boost::int16_t getInt16(const std::string& name) const;
376 
377  /*!
378  \brief Method for retrieving a 32-bit integer attribute value (4 bytes long).
379 
380  \param i The attribute index.
381 
382  \return The 32-bit integer attribute value in the given position.
383  */
384  virtual boost::int32_t getInt32(std::size_t i) const = 0;
385 
386  /*!
387  \brief Method for retrieving a 32-bit integer attribute value (4 bytes long).
388 
389  \param name The attribute name.
390 
391  \return The 32-bit integer attribute value with the given name.
392  */
393  virtual boost::int32_t getInt32(const std::string& name) const;
394 
395  /*!
396  \brief Method for retrieving a 64-bit integer attribute value (8 bytes long).
397 
398  \param i The attribute index.
399 
400  \return The 64-bit integer attribute value in the given position.
401  */
402  virtual boost::int64_t getInt64(std::size_t i) const = 0;
403 
404  /*!
405  \brief Method for retrieving a 64-bit integer attribute value (8 bytes long).
406 
407  \param name The attribute name.
408 
409  \return The 64-bit integer attribute value with the given name.
410  */
411  virtual boost::int64_t getInt64(const std::string& name) const;
412 
413  /*!
414  \brief Method for retrieving a boolean attribute value.
415 
416  \param i The attribute index.
417 
418  \return The boolean attribute value in the given position.
419  */
420  virtual bool getBool(std::size_t i) const = 0;
421 
422  /*!
423  \brief Method for retrieving a boolean attribute value.
424 
425  \param name The attribute name.
426 
427  \return The boolean attribute value with the given name.
428  */
429  virtual bool getBool(const std::string& name) const;
430 
431  /*!
432  \brief Method for retrieving a float attribute value.
433 
434  \param i The attribute index.
435 
436  \return The float attribute value in the given position.
437  */
438  virtual float getFloat(std::size_t i) const = 0;
439 
440  /*!
441  \brief Method for retrieving a float attribute value.
442 
443  \param name The attribute name.
444 
445  \return The float attribute value with the given name.
446  */
447  virtual float getFloat(const std::string& name) const;
448 
449  /*!
450  \brief Method for retrieving a double attribute value.
451 
452  \param i The attribute index.
453 
454  \return The double attribute value in the given position.
455  */
456  virtual double getDouble(std::size_t i) const = 0;
457 
458  /*!
459  \brief Method for retrieving a double attribute value.
460 
461  \param name The attribute name.
462 
463  \return The double attribute value with the given name.
464  */
465  virtual double getDouble(const std::string& name) const;
466 
467  /*!
468  \brief Method for retrieving a numeric attribute value.
469 
470  \param i The attribute index.
471 
472  \return The numeric attribute value in the given position.
473  */
474  virtual std::string getNumeric(std::size_t i) const = 0;
475 
476  /*!
477  \brief Method for retrieving a numeric attribute value.
478 
479  \param name The attribute name.
480 
481  \return The numeric attribute value with the given name.
482  */
483  virtual std::string getNumeric(const std::string& name) const;
484 
485  /*!
486  \brief Method for retrieving a string value attribute.
487 
488  \param i The attribute index.
489 
490  \return The string attribute value in the given position.
491  */
492  virtual std::string getString(std::size_t i) const = 0;
493 
494  /*!
495  \brief Method for retrieving a string attribute value.
496 
497  \param name The attribute name.
498 
499  \return The string attribute value with the given name.
500  */
501  virtual std::string getString(const std::string& name) const;
502 
503  /*!
504  \brief Method for retrieving a byte array.
505 
506  You can use this method in order to retrieve a BLOB data.
507 
508  \param i The attribute index.
509 
510  \return The byte array attribute.
511  */
512  virtual std::unique_ptr<te::dt::ByteArray> getByteArray(std::size_t i) const = 0;
513 
514  /*!
515  \brief Method for retrieving a byte array.
516 
517  You can use this method in order to retrieve a BLOB data.
518 
519  \param name The attribute name.
520 
521  \return The byte array attribute.
522  */
523  virtual std::unique_ptr<te::dt::ByteArray> getByteArray(const std::string& name) const;
524 
525  /*!
526  \brief Method for retrieving a geometric attribute value.
527 
528  \param i The attribute index.
529 
530  \return The geometric attribute value in the given position.
531  */
532  virtual std::unique_ptr<te::gm::Geometry> getGeometry(std::size_t i) const = 0;
533 
534  /*!
535  \brief Method for retrieving a geometric attribute value.
536 
537  \param name The attribute name.
538 
539  \return The geometric attribute value with the given name.
540  */
541  virtual std::unique_ptr<te::gm::Geometry> getGeometry(const std::string& name) const;
542 
543  /*!
544  \brief Method for retrieving a dataset item containing all the values in the current row
545 
546  \return The dataset item containing all the values of the current row
547  */
548  virtual std::unique_ptr<te::da::DataSetItem> getItem() const;
549 
550  /*!
551  \brief Method for retrieving a raster attribute value.
552 
553  \param i The attribute index.
554 
555  \return The raster attribute value in the given position.
556 
557 
558  \exception Exception It can throw an exception if:
559  <ul>
560  <li>something goes wrong during the data retrieval</li>
561  <li>the maximum number of simultaneous accesses has been reached</li>
562  </ul>
563  */
564  virtual std::unique_ptr<te::rst::Raster> getRaster(std::size_t i) const = 0;
565 
566  /*!
567  \brief Method for retrieving a raster attribute value.
568 
569  \param name The attribute name.
570 
571  \return The raster attribute value with the given name.
572 
573  \exception Exception It can throw an exception if:
574  <ul>
575  <li>something goes wrong during the data retrieval</li>
576  <li>the maximum number of simultaneous accesses has been reached</li>
577  </ul>
578  */
579  virtual std::unique_ptr<te::rst::Raster> getRaster(const std::string& name) const;
580 
581  /*!
582  \brief Method for retrieving a date and time attribute value.
583 
584  \param i The attribute index.
585 
586  \return The date and time attribute value in the given position.
587  */
588  virtual std::unique_ptr<te::dt::DateTime> getDateTime(std::size_t i) const = 0;
589 
590  /*!
591  \brief Method for retrieving a date and time attribute value.
592 
593  \param name The attribute name.
594 
595  \return The date and time attribute value with the given name.
596  */
597  virtual std::unique_ptr<te::dt::DateTime> getDateTime(const std::string& name) const;
598 
599  /*!
600  \brief Method for retrieving an array.
601 
602  \param i The attribute index.
603  */
604  virtual std::unique_ptr<te::dt::Array> getArray(std::size_t i) const = 0;
605 
606  /*!
607  \brief Method for retrieving an array.
608 
609  \param name The attribute name.
610 
611  \return An array. The caller will take its ownership.
612  */
613  virtual std::unique_ptr<te::dt::Array> getArray(const std::string& name) const;
614 
615  /*!
616  \brief Method for retrieving any other type of data value stored in the data source.
617 
618  This method can be use for extensible datatypes.
619 
620  \param i The attribute index.
621 
622  \return A pointer to the data value.
623  */
624  virtual std::unique_ptr<te::dt::AbstractData> getValue(std::size_t i) const;
625 
626  /*!
627  \brief Method for retrieving any other type of data value stored in the data source.
628 
629  This method can be use for extensible datatypes.
630 
631  \param name The attribute name.
632 
633  \return A pointer to the data value.
634  */
635  virtual std::unique_ptr<te::dt::AbstractData> getValue(const std::string& name) const;
636 
637  /*!
638  \brief Method for retrieving a data value as a string plain representation.
639 
640  \param i The attribute index.
641  \param precision The precision in the conversion.
642 
643  \return The attribute value in a string format.
644 
645  \note It is safe to call this method for any data type, the data source implementation will
646  take care of how to convert the internal representation to a string.
647  */
648  virtual std::string getAsString(std::size_t i, int precision = 0) const;
649 
650  /*!
651  \brief Method for retrieving a data value as a string plain representation.
652 
653  \param name The attribute name.
654  \param precision The precision in the conversion.
655 
656  \return The attribute value in a string format.
657 
658  \exception Exception if property not found.
659 
660  \note It is safe to call this method for any data type, the data source implementation will
661  take care of how to convert the internal representation to a string.
662  */
663  virtual std::string getAsString(const std::string& name, int precision = 0) const;
664 
665  /*!
666  \brief It checks if the attribute value is NULL.
667 
668  \param i The attribute index.
669 
670  \return True if the attribute value is NULL.
671  */
672  virtual bool isNull(std::size_t i) const = 0;
673 
674  /*!
675  \brief It checks if the attribute value is NULL.
676 
677  \param name The attribute name.
678 
679  \return True if the attribute value is NULL.
680  */
681  virtual bool isNull(const std::string& name) const;
682  //@}
683  };
684 
685  typedef boost::shared_ptr<DataSet> DataSetPtr;
686 
687  } // end namespace da
688 } // end namespace te
689 
690 
691 #endif // __TERRALIB_DATAACCESS_INTERNAL_DATASET_H
te::da::DataSet::DataSet
DataSet()
Default constructor.
Definition: DataSet.h:118
te::common::AccessPolicy
AccessPolicy
Supported data access policies (can be used as bitfield).
Definition: Enums.h:40
te::common::TraverseType
TraverseType
A dataset can be traversed in two ways:
Definition: Enums.h:53
te
TerraLib.
Definition: AddressGeocodingOp.h:51
te::da::DataSet
A dataset is the unit of information manipulated by the data access module of TerraLib.
Definition: DataSet.h:113
te::da::DataSetPtr
boost::shared_ptr< DataSet > DataSetPtr
Definition: DataSet.h:685
te::da::DataSet::~DataSet
virtual ~DataSet()
Virtual destructor.
Definition: DataSet.h:121
TEDATAACCESSEXPORT
#define TEDATAACCESSEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:97