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