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