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/CharEncodingConv.h"
31 #include "../../common/Enums.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 property character encoding at position pos.
168 
169  \param i The property the position of interest.
170 
171  \return The property character encoding.
172 
173  \note The property at position pos must be a textual property.
174 
175  \exception Exception It throws an exception if the property at position pos is not a textual property.
176  */
177  virtual te::common::CharEncoding getPropertyCharEncoding(std::size_t i) const = 0;
178 
179  /*!
180  \brief It returns the underlying dataset name of the property at position pos.
181 
182  \param i The property position of interest.
183 
184  \return The underlying dataset name of the property at position pos.
185  */
186  virtual std::string getDatasetNameOfProperty(std::size_t i) const = 0;
187  //@}
188 
189  /** @name Collection Methods
190  * Methods for getting/setting atomic datasets.
191  */
192  //@{
193 
194  /*!
195  \brief It returns true if the collection is empty.
196 
197  \return True, if the collection is empty.
198  */
199  virtual bool isEmpty() const = 0;
200 
201  /*!
202  \brief It returns true if the dataset is connected and false if it is disconnected.
203  A dataset can be connected or disconnected. A connected dataset, after its creation through
204  the data source transactor, continues to depend on the connection given by its associated
205  data source. Differently, a disconnected dataset, after its creation, no more depends of the
206  connection given by the data source, and it continues to live after the connection has been
207  released to the data source.
208 
209  \return True, if the dataset is connected, or false if it is disconnected.
210  */
211  virtual bool isConnected() const = 0;
212 
213  /*!
214  \brief It returns the collection size, if it is known.
215 
216  It may return std::string::npos if the size is not known,
217  or it would be too costly to compute it.
218 
219  \return The size of the collection, if it is known.
220  */
221  virtual std::size_t size() const = 0;
222 
223  /*!
224  \brief It computes the bounding rectangle for a spatial property of the dataset.
225 
226  \param i The position of a spatial property to get its bounding box.
227 
228  \pre The position i must be associated to a spatial property of the dataset.
229 
230  \exception Exception It throws an exception if something goes wrong during MBR search.
231 
232  \return The spatial property bounding rectangle, or an invalid box, if none is found.
233  */
234  virtual std::auto_ptr<te::gm::Envelope> getExtent(std::size_t i) = 0;
235 
236  /*!
237  \brief It moves the internal pointer to the next item of the collection.
238 
239  You always has to call this method in order to move the internal pointer to the first
240  item in the collection. This method can be used to traverse a dataset.
241 
242  \return True if the internal pointer is on a valid item, or false otherwise.
243 
244  \note All dataset types support this method: FORWARDONLY, BIDIRECTIONAL and RANDOM.
245  */
246  virtual bool moveNext() = 0;
247 
248  /*!
249  \brief It moves the internal pointer to the previous item of the collection.
250 
251  \return True, if the internal pointer (cursor position) is on a valid item, or false otherwise.
252 
253  \note This method is not supported by FORWARDONLY datasets.
254  */
255  virtual bool movePrevious() = 0;
256 
257  /*!
258  \brief It moves the internal pointer to a position before the first item in the collection.
259 
260  \return True, if it was possible to move to a sentinel position before the first item in the collection.
261 
262  \note This method is not supported by FORWARDONLY datasets.
263  */
264  virtual bool moveBeforeFirst() = 0;
265 
266  /*!
267  \brief It moves the internal pointer to the first item in the collection.
268 
269  \return True, if it was possible to move to the first item in the collection.
270 
271  \note This method is not supported by FORWARDONLY datasets.
272  */
273  virtual bool moveFirst() = 0;
274 
275  /*!
276  \brief It sets the dataset internal pointer to the last item in the collection.
277 
278  \return True, if it was possible to move to the last item in the collection.
279  */
280  virtual bool moveLast() = 0;
281 
282  /*!
283  \brief It moves the dataset internal pointer to a given position.
284 
285  \param i The position the dataset internal pointer must be set up.
286 
287  \return True, if it was possible to move the dataset reading to the given position.
288 
289  \note The first item in the collection starts at address 0.
290  */
291  virtual bool move(std::size_t i) = 0;
292 
293  /*!
294  \brief It tells if the dataset internal pointer is on the first element of the collection or not.
295 
296  \return True if the dataset internal pointer is on the first element otherwise it returns false.
297  */
298  virtual bool isAtBegin() const = 0;
299 
300  /*!
301  \brief It tells if the dataset internal pointer is in a position before the first element of the collection or not.
302 
303  \return True, if the dataset internal pointer is in a position before the first element otherwise it returns false.
304  */
305  virtual bool isBeforeBegin() const = 0;
306 
307  /*!
308  \brief It tells if the dataset internal pointer is on the last element of the collection.
309 
310  \return True, if the dataset internal pointer is on the last element otherwise it returns false.
311  */
312  virtual bool isAtEnd() const = 0;
313 
314  /*!
315  \brief It tells if the dataset internal pointer is on the sentinel position after the last element of the collection or not.
316 
317  \return True, if the dataset internal pointer is on the sentinel position after the last element otherwise it returns false.
318  */
319  virtual bool isAfterEnd() const = 0;
320 
321  //@}
322 
323  /** @name DataSet Element Properties
324  * Methods for retrieving/setting the dataset item component values without the need to explicitly instantiate an item via getItem method.
325  */
326  //@{
327 
328  /*!
329  \brief Method for retrieving a signed character attribute value (1 byte long).
330 
331  \param i The attribute index.
332 
333  \return The signed character attribute value (1 byte long) in the given position.
334  */
335  virtual char getChar(std::size_t i) const = 0;
336 
337  /*!
338  \brief Method for retrieving a signed character attribute value (1 byte long).
339 
340  \param name The attribute name.
341 
342  \return The signed character attribute value (1 byte long) with the given name.
343  */
344  virtual char getChar(const std::string& name) const;
345 
346  /*!
347  \brief Method for retrieving an unsigned character attribute value (1 byte long).
348 
349  \param i The attribute index.
350 
351  \return The unsigned character attribute value (1 byte long) in the given position.
352  */
353  virtual unsigned char getUChar(std::size_t i) const = 0;
354 
355  /*!
356  \brief Method for retrieving an unsigned character attribute value (1 byte long).
357 
358  \param name The attribute name.
359 
360  \return The unsigned character attribute value (1 byte long) with the given name.
361  */
362  virtual unsigned char getUChar(const std::string& name) const;
363 
364  /*!
365  \brief Method for retrieving a 16-bit integer attribute value (2 bytes long).
366 
367  \param i The attribute index.
368 
369  \return The 16-bit integer attribute value (2 bytes long) in the given position.
370  */
371  virtual boost::int16_t getInt16(std::size_t i) const = 0;
372 
373  /*!
374  \brief Method for retrieving a 16-bit integer attribute value (2 bytes long).
375 
376  \param name The attribute name.
377 
378  \return The 16-bit integer attribute value (2 bytes long) with the given name.
379  */
380  virtual boost::int16_t getInt16(const std::string& name) const;
381 
382  /*!
383  \brief Method for retrieving a 32-bit integer attribute value (4 bytes long).
384 
385  \param i The attribute index.
386 
387  \return The 32-bit integer attribute value in the given position.
388  */
389  virtual boost::int32_t getInt32(std::size_t i) const = 0;
390 
391  /*!
392  \brief Method for retrieving a 32-bit integer attribute value (4 bytes long).
393 
394  \param name The attribute name.
395 
396  \return The 32-bit integer attribute value with the given name.
397  */
398  virtual boost::int32_t getInt32(const std::string& name) const;
399 
400  /*!
401  \brief Method for retrieving a 64-bit integer attribute value (8 bytes long).
402 
403  \param i The attribute index.
404 
405  \return The 64-bit integer attribute value in the given position.
406  */
407  virtual boost::int64_t getInt64(std::size_t i) const = 0;
408 
409  /*!
410  \brief Method for retrieving a 64-bit integer attribute value (8 bytes long).
411 
412  \param name The attribute name.
413 
414  \return The 64-bit integer attribute value with the given name.
415  */
416  virtual boost::int64_t getInt64(const std::string& name) const;
417 
418  /*!
419  \brief Method for retrieving a boolean attribute value.
420 
421  \param i The attribute index.
422 
423  \return The boolean attribute value in the given position.
424  */
425  virtual bool getBool(std::size_t i) const = 0;
426 
427  /*!
428  \brief Method for retrieving a boolean attribute value.
429 
430  \param name The attribute name.
431 
432  \return The boolean attribute value with the given name.
433  */
434  virtual bool getBool(const std::string& name) const;
435 
436  /*!
437  \brief Method for retrieving a float attribute value.
438 
439  \param i The attribute index.
440 
441  \return The float attribute value in the given position.
442  */
443  virtual float getFloat(std::size_t i) const = 0;
444 
445  /*!
446  \brief Method for retrieving a float attribute value.
447 
448  \param name The attribute name.
449 
450  \return The float attribute value with the given name.
451  */
452  virtual float getFloat(const std::string& name) const;
453 
454  /*!
455  \brief Method for retrieving a double attribute value.
456 
457  \param i The attribute index.
458 
459  \return The double attribute value in the given position.
460  */
461  virtual double getDouble(std::size_t i) const = 0;
462 
463  /*!
464  \brief Method for retrieving a double attribute value.
465 
466  \param name The attribute name.
467 
468  \return The double attribute value with the given name.
469  */
470  virtual double getDouble(const std::string& name) const;
471 
472  /*!
473  \brief Method for retrieving a numeric attribute value.
474 
475  \param i The attribute index.
476 
477  \return The numeric attribute value in the given position.
478  */
479  virtual std::string getNumeric(std::size_t i) const = 0;
480 
481  /*!
482  \brief Method for retrieving a numeric attribute value.
483 
484  \param name The attribute name.
485 
486  \return The numeric attribute value with the given name.
487  */
488  virtual std::string getNumeric(const std::string& name) const;
489 
490  /*!
491  \brief Method for retrieving a string value attribute.
492 
493  \param i The attribute index.
494 
495  \return The string attribute value in the given position.
496  */
497  virtual std::string getString(std::size_t i) const = 0;
498 
499  /*!
500  \brief Method for retrieving a string attribute value.
501 
502  \param name The attribute name.
503 
504  \return The string attribute value with the given name.
505  */
506  virtual std::string getString(const std::string& name) const;
507 
508  /*!
509  \brief Method for retrieving a byte array.
510 
511  You can use this method in order to retrieve a BLOB data.
512 
513  \param i The attribute index.
514 
515  \return The byte array attribute.
516  */
517  virtual std::auto_ptr<te::dt::ByteArray> getByteArray(std::size_t i) const = 0;
518 
519  /*!
520  \brief Method for retrieving a byte array.
521 
522  You can use this method in order to retrieve a BLOB data.
523 
524  \param name The attribute name.
525 
526  \return The byte array attribute.
527  */
528  virtual std::auto_ptr<te::dt::ByteArray> getByteArray(const std::string& name) const;
529 
530  /*!
531  \brief Method for retrieving a geometric attribute value.
532 
533  \param i The attribute index.
534 
535  \return The geometric attribute value in the given position.
536  */
537  virtual std::auto_ptr<te::gm::Geometry> getGeometry(std::size_t i) const = 0;
538 
539  /*!
540  \brief Method for retrieving a geometric attribute value.
541 
542  \param name The attribute name.
543 
544  \return The geometric attribute value with the given name.
545  */
546  virtual std::auto_ptr<te::gm::Geometry> getGeometry(const std::string& name) const;
547 
548  /*!
549  \brief Method for retrieving a raster attribute value.
550 
551  \param i The attribute index.
552 
553  \return The raster attribute value in the given position.
554 
555 
556  \exception Exception It can throw an exception if:
557  <ul>
558  <li>something goes wrong during the data retrieval</li>
559  <li>the maximum number of simultaneous accesses has been reached</li>
560  </ul>
561  */
562  virtual std::auto_ptr<te::rst::Raster> getRaster(std::size_t i) const = 0;
563 
564  /*!
565  \brief Method for retrieving a raster attribute value.
566 
567  \param name The attribute name.
568 
569  \return The raster attribute value with the given name.
570 
571  \exception Exception It can throw an exception if:
572  <ul>
573  <li>something goes wrong during the data retrieval</li>
574  <li>the maximum number of simultaneous accesses has been reached</li>
575  </ul>
576  */
577  virtual std::auto_ptr<te::rst::Raster> getRaster(const std::string& name) const;
578 
579  /*!
580  \brief Method for retrieving a date and time attribute value.
581 
582  \param i The attribute index.
583 
584  \return The date and time attribute value in the given position.
585  */
586  virtual std::auto_ptr<te::dt::DateTime> getDateTime(std::size_t i) const = 0;
587 
588  /*!
589  \brief Method for retrieving a date and time attribute value.
590 
591  \param name The attribute name.
592 
593  \return The date and time attribute value with the given name.
594  */
595  virtual std::auto_ptr<te::dt::DateTime> getDateTime(const std::string& name) const;
596 
597  /*!
598  \brief Method for retrieving an array.
599 
600  \param i The attribute index.
601  */
602  virtual std::auto_ptr<te::dt::Array> getArray(std::size_t i) const = 0;
603 
604  /*!
605  \brief Method for retrieving an array.
606 
607  \param name The attribute name.
608 
609  \return An array. The caller will take its ownership.
610  */
611  virtual std::auto_ptr<te::dt::Array> getArray(const std::string& name) const;
612 
613  /*!
614  \brief Method for retrieving any other type of data value stored in the data source.
615 
616  This method can be use for extensible datatypes.
617 
618  \param i The attribute index.
619 
620  \return A pointer to the data value.
621  */
622  virtual std::auto_ptr<te::dt::AbstractData> getValue(std::size_t i) const;
623 
624  /*!
625  \brief Method for retrieving any other type of data value stored in the data source.
626 
627  This method can be use for extensible datatypes.
628 
629  \param name The attribute name.
630 
631  \return A pointer to the data value.
632  */
633  virtual std::auto_ptr<te::dt::AbstractData> getValue(const std::string& name) const;
634 
635  /*!
636  \brief Method for retrieving a data value as a string plain representation.
637 
638  \param i The attribute index.
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(std::size_t i, int precision = 0) const;
647 
648  /*!
649  \brief Method for retrieving a data value as a string plain representation.
650 
651  \param name The attribute name.
652  \param precision The precision in the conversion.
653 
654  \return The attribute value in a string format.
655 
656  \note It is safe to call this method for any data type, the data source implementation will
657  take care of how to convert the internal representation to a string.
658  */
659  virtual std::string getAsString(const std::string& name, int precision = 0) const;
660 
661  /*!
662  \brief It checks if the attribute value is NULL.
663 
664  \param i The attribute index.
665 
666  \return True if the attribute value is NULL.
667  */
668  virtual bool isNull(std::size_t i) const = 0;
669 
670  /*!
671  \brief It checks if the attribute value is NULL.
672 
673  \param name The attribute name.
674 
675  \return True if the attribute value is NULL.
676  */
677  virtual bool isNull(const std::string& name) const;
678  //@}
679  };
680 
681  typedef boost::shared_ptr<DataSet> DataSetPtr;
682 
683  } // end namespace da
684 } // end namespace te
685 
686 
687 #endif // __TERRALIB_DATAACCESS_INTERNAL_DATASET_H
te::mem::DataSetPtr
boost::shared_ptr< DataSet > DataSetPtr
Definition: DataSet.h:391
te::common::CharEncoding
CharEncoding
Supported charsets (character encoding).
Definition: CharEncodingConv.h:45
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::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