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::unique_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  \brief It tells if the dataset internal pointer is on a valid position.
310 
311  \return True, if the dataset internal pointer is on a valid position.
312  */
313  virtual bool isPositionValid() const = 0;
314 
315  //@}
316 
317  /** @name DataSet Element Properties
318  * Methods for retrieving/setting the dataset item component values without the need to explicitly instantiate an item via getItem method.
319  */
320  //@{
321 
322  /*!
323  \brief Method for retrieving a signed character attribute value (1 byte long).
324 
325  \param i The attribute index.
326 
327  \return The signed character attribute value (1 byte long) in the given position.
328  */
329  virtual char getChar(std::size_t i) const = 0;
330 
331  /*!
332  \brief Method for retrieving a signed character attribute value (1 byte long).
333 
334  \param name The attribute name.
335 
336  \return The signed character attribute value (1 byte long) with the given name.
337  */
338  virtual char getChar(const std::string& name) const;
339 
340  /*!
341  \brief Method for retrieving an unsigned character attribute value (1 byte long).
342 
343  \param i The attribute index.
344 
345  \return The unsigned character attribute value (1 byte long) in the given position.
346  */
347  virtual unsigned char getUChar(std::size_t i) const = 0;
348 
349  /*!
350  \brief Method for retrieving an unsigned character attribute value (1 byte long).
351 
352  \param name The attribute name.
353 
354  \return The unsigned character attribute value (1 byte long) with the given name.
355  */
356  virtual unsigned char getUChar(const std::string& name) const;
357 
358  /*!
359  \brief Method for retrieving a 16-bit integer attribute value (2 bytes long).
360 
361  \param i The attribute index.
362 
363  \return The 16-bit integer attribute value (2 bytes long) in the given position.
364  */
365  virtual boost::int16_t getInt16(std::size_t i) const = 0;
366 
367  /*!
368  \brief Method for retrieving a 16-bit integer attribute value (2 bytes long).
369 
370  \param name The attribute name.
371 
372  \return The 16-bit integer attribute value (2 bytes long) with the given name.
373  */
374  virtual boost::int16_t getInt16(const std::string& name) const;
375 
376  /*!
377  \brief Method for retrieving a 32-bit integer attribute value (4 bytes long).
378 
379  \param i The attribute index.
380 
381  \return The 32-bit integer attribute value in the given position.
382  */
383  virtual boost::int32_t getInt32(std::size_t i) const = 0;
384 
385  /*!
386  \brief Method for retrieving a 32-bit integer attribute value (4 bytes long).
387 
388  \param name The attribute name.
389 
390  \return The 32-bit integer attribute value with the given name.
391  */
392  virtual boost::int32_t getInt32(const std::string& name) const;
393 
394  /*!
395  \brief Method for retrieving a 64-bit integer attribute value (8 bytes long).
396 
397  \param i The attribute index.
398 
399  \return The 64-bit integer attribute value in the given position.
400  */
401  virtual boost::int64_t getInt64(std::size_t i) const = 0;
402 
403  /*!
404  \brief Method for retrieving a 64-bit integer attribute value (8 bytes long).
405 
406  \param name The attribute name.
407 
408  \return The 64-bit integer attribute value with the given name.
409  */
410  virtual boost::int64_t getInt64(const std::string& name) const;
411 
412  /*!
413  \brief Method for retrieving a boolean attribute value.
414 
415  \param i The attribute index.
416 
417  \return The boolean attribute value in the given position.
418  */
419  virtual bool getBool(std::size_t i) const = 0;
420 
421  /*!
422  \brief Method for retrieving a boolean attribute value.
423 
424  \param name The attribute name.
425 
426  \return The boolean attribute value with the given name.
427  */
428  virtual bool getBool(const std::string& name) const;
429 
430  /*!
431  \brief Method for retrieving a float attribute value.
432 
433  \param i The attribute index.
434 
435  \return The float attribute value in the given position.
436  */
437  virtual float getFloat(std::size_t i) const = 0;
438 
439  /*!
440  \brief Method for retrieving a float attribute value.
441 
442  \param name The attribute name.
443 
444  \return The float attribute value with the given name.
445  */
446  virtual float getFloat(const std::string& name) const;
447 
448  /*!
449  \brief Method for retrieving a double attribute value.
450 
451  \param i The attribute index.
452 
453  \return The double attribute value in the given position.
454  */
455  virtual double getDouble(std::size_t i) const = 0;
456 
457  /*!
458  \brief Method for retrieving a double attribute value.
459 
460  \param name The attribute name.
461 
462  \return The double attribute value with the given name.
463  */
464  virtual double getDouble(const std::string& name) const;
465 
466  /*!
467  \brief Method for retrieving a numeric attribute value.
468 
469  \param i The attribute index.
470 
471  \return The numeric attribute value in the given position.
472  */
473  virtual std::string getNumeric(std::size_t i) const = 0;
474 
475  /*!
476  \brief Method for retrieving a numeric attribute value.
477 
478  \param name The attribute name.
479 
480  \return The numeric attribute value with the given name.
481  */
482  virtual std::string getNumeric(const std::string& name) const;
483 
484  /*!
485  \brief Method for retrieving a string value attribute.
486 
487  \param i The attribute index.
488 
489  \return The string attribute value in the given position.
490  */
491  virtual std::string getString(std::size_t i) const = 0;
492 
493  /*!
494  \brief Method for retrieving a string attribute value.
495 
496  \param name The attribute name.
497 
498  \return The string attribute value with the given name.
499  */
500  virtual std::string getString(const std::string& name) const;
501 
502  /*!
503  \brief Method for retrieving a byte array.
504 
505  You can use this method in order to retrieve a BLOB data.
506 
507  \param i The attribute index.
508 
509  \return The byte array attribute.
510  */
511  virtual std::unique_ptr<te::dt::ByteArray> getByteArray(std::size_t i) const = 0;
512 
513  /*!
514  \brief Method for retrieving a byte array.
515 
516  You can use this method in order to retrieve a BLOB data.
517 
518  \param name The attribute name.
519 
520  \return The byte array attribute.
521  */
522  virtual std::unique_ptr<te::dt::ByteArray> getByteArray(const std::string& name) const;
523 
524  /*!
525  \brief Method for retrieving a geometric attribute value.
526 
527  \param i The attribute index.
528 
529  \return The geometric attribute value in the given position.
530  */
531  virtual std::unique_ptr<te::gm::Geometry> getGeometry(std::size_t i) const = 0;
532 
533  /*!
534  \brief Method for retrieving a geometric attribute value.
535 
536  \param name The attribute name.
537 
538  \return The geometric attribute value with the given name.
539  */
540  virtual std::unique_ptr<te::gm::Geometry> getGeometry(const std::string& name) const;
541 
542  /*!
543  \brief Method for retrieving a raster attribute value.
544 
545  \param i The attribute index.
546 
547  \return The raster attribute value in the given position.
548 
549 
550  \exception Exception It can throw an exception if:
551  <ul>
552  <li>something goes wrong during the data retrieval</li>
553  <li>the maximum number of simultaneous accesses has been reached</li>
554  </ul>
555  */
556  virtual std::unique_ptr<te::rst::Raster> getRaster(std::size_t i) const = 0;
557 
558  /*!
559  \brief Method for retrieving a raster attribute value.
560 
561  \param name The attribute name.
562 
563  \return The raster attribute value with the given name.
564 
565  \exception Exception It can throw an exception if:
566  <ul>
567  <li>something goes wrong during the data retrieval</li>
568  <li>the maximum number of simultaneous accesses has been reached</li>
569  </ul>
570  */
571  virtual std::unique_ptr<te::rst::Raster> getRaster(const std::string& name) const;
572 
573  /*!
574  \brief Method for retrieving a date and time attribute value.
575 
576  \param i The attribute index.
577 
578  \return The date and time attribute value in the given position.
579  */
580  virtual std::unique_ptr<te::dt::DateTime> getDateTime(std::size_t i) const = 0;
581 
582  /*!
583  \brief Method for retrieving a date and time attribute value.
584 
585  \param name The attribute name.
586 
587  \return The date and time attribute value with the given name.
588  */
589  virtual std::unique_ptr<te::dt::DateTime> getDateTime(const std::string& name) const;
590 
591  /*!
592  \brief Method for retrieving an array.
593 
594  \param i The attribute index.
595  */
596  virtual std::unique_ptr<te::dt::Array> getArray(std::size_t i) const = 0;
597 
598  /*!
599  \brief Method for retrieving an array.
600 
601  \param name The attribute name.
602 
603  \return An array. The caller will take its ownership.
604  */
605  virtual std::unique_ptr<te::dt::Array> getArray(const std::string& name) const;
606 
607  /*!
608  \brief Method for retrieving any other type of data value stored in the data source.
609 
610  This method can be use for extensible datatypes.
611 
612  \param i The attribute index.
613 
614  \return A pointer to the data value.
615  */
616  virtual std::unique_ptr<te::dt::AbstractData> getValue(std::size_t i) const;
617 
618  /*!
619  \brief Method for retrieving any other type of data value stored in the data source.
620 
621  This method can be use for extensible datatypes.
622 
623  \param name The attribute name.
624 
625  \return A pointer to the data value.
626  */
627  virtual std::unique_ptr<te::dt::AbstractData> getValue(const std::string& name) const;
628 
629  /*!
630  \brief Method for retrieving a data value as a string plain representation.
631 
632  \param i The attribute index.
633  \param precision The precision in the conversion.
634 
635  \return The attribute value in a string format.
636 
637  \note It is safe to call this method for any data type, the data source implementation will
638  take care of how to convert the internal representation to a string.
639  */
640  virtual std::string getAsString(std::size_t i, int precision = 0) const;
641 
642  /*!
643  \brief Method for retrieving a data value as a string plain representation.
644 
645  \param name The attribute name.
646  \param precision The precision in the conversion.
647 
648  \return The attribute value in a string format.
649 
650  \exception Exception if property not found.
651 
652  \note It is safe to call this method for any data type, the data source implementation will
653  take care of how to convert the internal representation to a string.
654  */
655  virtual std::string getAsString(const std::string& name, int precision = 0) const;
656 
657  /*!
658  \brief It checks if the attribute value is NULL.
659 
660  \param i The attribute index.
661 
662  \return True if the attribute value is NULL.
663  */
664  virtual bool isNull(std::size_t i) const = 0;
665 
666  /*!
667  \brief It checks if the attribute value is NULL.
668 
669  \param name The attribute name.
670 
671  \return True if the attribute value is NULL.
672  */
673  virtual bool isNull(const std::string& name) const;
674  //@}
675  };
676 
677  typedef boost::shared_ptr<DataSet> DataSetPtr;
678 
679  } // end namespace da
680 } // end namespace te
681 
682 
683 #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
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:112
te::da::DataSetPtr
boost::shared_ptr< DataSet > DataSetPtr
Definition: DataSet.h:677
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