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/stmemory/DataSet.h
22 
23  \brief Implementation of an in-memory data set that contains spatiotemporal observations indexed by time and space.
24 */
25 
26 #ifndef __TERRALIB_STMEMORY_INTERNAL_DATASET_H
27 #define __TERRALIB_STMEMORY_INTERNAL_DATASET_H
28 
29 // TerraLib
30 #include "../dataaccess/dataset/DataSet.h"
31 #include "../sam/rtree/Index.h"
32 #include "Config.h"
33 
34 // STL
35 #include <map>
36 
37 // Boost
38 #include <boost/shared_ptr.hpp>
39 
40 namespace te { namespace da { class DataSetType; } }
41 namespace te { namespace dt { class DateTimePeriod; } }
42 namespace te { namespace mem { class DataSetItem; } }
43 
44 namespace te
45 {
46  namespace stmem
47  {
48  // Typedefs
49  typedef boost::shared_ptr<te::mem::DataSetItem> DateSetItemShrPtr;
50  typedef std::pair<te::dt::DateTime*, DateSetItemShrPtr> TimeAndDateSetItemPair;
51  typedef std::multimap<te::dt::DateTime*, DateSetItemShrPtr, te::dt::CompareDateTime> TimeToDataSetItemMap;
52 
53  /*!
54  \class DataSet
55 
56  \brief Implementation of a in-memory data set that contains spatiotemporal
57  observations indexed by time and space.
58 
59  \sa te::da::DataSet
60  */
61  class TESTMEMORYEXPORT DataSet : public te::da::DataSet
62  {
63  public:
64 
65  /*!
66  \brief It constructs an empty in-memory dataset indexed by time and space.
67 
68  \param dt the schema of the in-memory observation DataSet that will be created.
69  \param tpPropIdx the property index of the DataSetType "dt" that contains the observation phenomenon time.
70  \param gmPropIdx the property index of the DataSetType "dt" that contains geometries.
71 
72  \note DataSet will NOT take the ownership of the given pointer.
73  */
74  DataSet(const te::da::DataSetType* type, int tpPropIdx);
75 
76  /*!
77  \brief It constructs an empty in-memory dataset indexed by time and space.
78 
79  \param dt the schema of the in-memory observation DataSet that will be created.
80  \param tpPropIdx the property index of the DataSetType "dt" that contains the observation phenomenon time.
81  \param gmPropIdx the property index of the DataSetType "dt" that contains geometries.
82 
83  \note DataSet will NOT take the ownership of the given pointer.
84  */
85  DataSet(const te::da::DataSetType* type, int tpPropIdx, int gmPropIdx);
86 
87  /*!
88  \brief It constructs an empty in-memory dataset indexed by time and space.
89 
90  \param dt the schema of the in-memory observation DataSet that will be created.
91  \param begTimePropIdx the property index of the DataSetType "dt" that contains the observation phenomenon beginning time.
92  \param endTimePropIdx the property index of the DataSetType "dt" that contains the observation phenomenon end time.
93  \param gmPropIdx the property index of the DataSetType "dt" that contains geometries.
94 
95  \note DataSet will NOT take the ownership of the given pointer.
96  */
97  DataSet(const te::da::DataSetType* type, int begTimePropIdx, int endTimePropIdx, int gmPropIdx);
98 
99  /*!
100  \brief It constructs an empty in-memory dataset indexed by time and space.
101 
102  \param pnames The names of the properties.
103  \param ptypes The types of the properties.
104  \param begTimePropIdx The property index of the ptypes vector that contains the observation phenomenon beginning time.
105  \param endTimePropIdx The property index of the ptypes vector that contains the observation phenomenon end time.
106  \param gmPropIdx The property index of the ptypes vector that contains geometries.
107  */
108  DataSet(const std::vector<std::string>& pnames, const std::vector<int>& ptyes, const std::map<int, te::common::CharEncoding>& encodings, int begTimePropIdx, int endTimePropIdx, int gmPropIdx);
109 
110 
111  /*!
112  \brief It constructs an in-memory observation dataset from a given data set.
113 
114  It creates a new in-memory observation dataset with the items from the given dataset.
115 
116  \param ds the dataset which will provide the observations.
117  \param tpPropIdx the property index of the DataSet "ds" that contains the observation phenomenon time
118  \param gmPropIdx the property index of the DataSet "ds" that contains geometries
119  \param limit The number of items to be copied. Use 0 to copy all items.
120 
121  \pre You must assure that ds is a valid item to be read.
122  \pre You must assure that ds has a valid type associated to it, that is, getType() is valid.
123 
124  \note This constructor will use the method "moveNext()" of the source dataset (ds)
125  in order to read its items. It will start reading the given
126  dataset in the current position. So, the caller is responsible for
127  informing the dataset in the right position to start processing it.
128 
129  \note DataSet will NOT take the ownership of the given ds pointer.
130 
131  \note The new dataset will not have a transactor associated to it.
132  */
133  DataSet(te::da::DataSet* ds, int tpPropIdx, int gmPropIdx = -1, unsigned int limit = 0);
134 
135  /*!
136  \brief It constructs an in-memory observation dataset from a given data set.
137 
138  It creates a new in-memory observation dataset with the items from the given dataset.
139 
140  \param ds the dataset which will provide the observations.
141  \param begTimePropIdx the property index of the DataSetType "dt" that contains the observation phenomenon beginning time.
142  \param endTimePropIdx the property index of the DataSetType "dt" that contains the observation phenomenon end time.
143  \param gmPropIdx the property index of the DataSet "ds" that contains geometries
144  \param limit The number of items to be copied. Use 0 to copy all items.
145 
146  \pre You must assure that ds is in a valid item to be read.
147  \pre You must assure that ds has a valid type associated to it, that is, getType() is valid.
148 
149  \note This constructor will use the method "moveNext()" of the source dataset (ds)
150  in order to read its items. It will start reading the given
151  dataset in the current position. So, the caller is responsible for
152  informing the dataset in the right position to start processing it.
153 
154  \note DataSet will NOT take the ownership of the given ds pointer.
155 
156  \note The new dataset will not have a transactor associated to it.
157  */
158  DataSet(te::da::DataSet* ds, int begTimePropIdx, int endTimePropIdx, int gmPropIdx, unsigned int limit);
159 
160  /*!
161  \brief Regular copy constructor.
162 
163  It creates a new in-memory observation dataset with the items from the rhs dataset.
164 
165  \param rhs The dataset which will provide the items.
166  \param deepCopy If true the new dataset instance will clone all dataset items from the source dataset (rhs), otherwise it will share all items.
167 
168  \pre You must assure that rhs is in a valid item to be read.
169  \pre You must assure that rhs has a valid type associated to it, that is, getType() is valid.
170 
171  \note This constructor will copy all items from the given DataSet rhs,
172  independently on its current position.
173  */
174  DataSet(const DataSet& rhs, const bool deepCopy = false);
175 
176  /*!
177  \brief Assignment operator
178 
179  \note The left-side DataSet will share all observations or items of the right-side DataSet.
180  \note If the caller does not want to share the items, it must use the method clone.
181  */
182  DataSet& operator= (const DataSet& rhs);
183 
184  /*! \brief Destructor. */
185  ~DataSet();
186 
187  /*!
188  \brief It copies up to limit items from the source dataset.
189 
190  \param src The source dataset with the items that will be copied.
191  \param limit The number of items to be copied. Use 0 to copy all items.
192 
193  \pre The internal DataSetType and ObservationSetType must be already created and valid.
194  \pre The internal DataSetType must be equal to the given DataSet src
195 
196  \note This method will call moveNext() for the source dataset
197  in order to read its items. It will start reading the given
198  dataset in the current position. So, the caller is responsible for
199  informing the dataset in the right position to start processing it.
200  */
201  void copy(te::da::DataSet* src, unsigned int limit = 0);
202 
203  /*!
204  \brief It copies up to limit items from the source dataset (src).
205 
206  \param src The source dataset with the items that will be copied.
207  \param properties The list of properties which will be considered in the copy.
208  \param limit The number of items to be copied. Use 0 to copy all items.
209 
210  \pre The properties in the property vector must come from the source dataset (src) schema. In other
211  words, they must be valid pointers in the src dataset type.
212  \pre The internal DataSetType must be already created, using the given properties.
213 
214  \note This method will call moveNext() for the source dataset
215  in order to read its items. It will start reading the given
216  dataset in the current position. So, the caller is responsible for
217  informing the dataset in the right position to start processing it.
218  */
219  void copy(te::da::DataSet* src, const std::vector<std::size_t>& properties, unsigned int limit = 0);
220 
221  /*!
222  \brief It returns a reference to the internal observation set.
223 
224  \return A reference to the internal observation set.
225  */
226  const TimeToDataSetItemMap& getData() const;
227 
228  /*!
229  \brief It returns the index of the property that contains the observed geometries.
230 
231  \return An index of the property that conatins the observed geometries.
232  */
233  int getGeomPropIdx() const;
234 
235  /*!
236  \brief It returns the index of the property that contains the beginning phenomenon time.
237 
238  \return An index of the property that conatins the beginning phenomenon time.
239  */
240  int getBeginTimePropIdx() const;
241 
242  /*!
243  \brief It returns the index of the property that contains the end phenomenon time.
244 
245  \return An index of the property that conatins the end phenomenon time.
246  */
247  int getEndTimePropIdx() const;
248 
249  /*!
250  \brief It adds an existing item to the dataset.
251 
252  This method must be used when the user wants to share
253  the same item among DataSets. After adding the item,
254  it updates the internal RTree.
255 
256  \param item An existing item coming from another DataSet.
257 
258  \pre The item schema must be compatible with the dataset items.
259 
260  \note The first element of the pair (DateTime*) will be cloned.
261  \note It will not take the ownership of the first element of the given pair.
262  */
263  void add(const std::pair<te::dt::DateTime*, DateSetItemShrPtr>& item);
264 
265  /*!
266  \brief It adds a new item to the dataset and takes its ownership.
267 
268  \param item The item to be added to the dataset.
269 
270  \pre The item schema must be compatible with the dataset items.
271 
272  \note It will take the ownership of the item pointer.
273  */
274  void add(te::mem::DataSetItem* item);
275 
276  /*!
277  \brief It returns the temporal extent of the observations.
278 
279  \return The temporal extent of the observations.
280 
281  \note The caller will take the ownership of the output pointer.
282  */
283  std::auto_ptr<te::dt::DateTimePeriod> getTemporalExtent() const;
284 
285  /*!
286  \brief It returns a clone of the DataSet
287 
288  \return a clone of the DataSet
289 
290  \note The caller will take the ownership of the returned pointer.
291  */
292  std::auto_ptr<DataSet> clone() const;
293 
294  /*!
295  \brief It returns a new DataSet, based on a given spatial filter
296 
297  \param e A given envelope
298  \param r A given spatial relation.
299 
300  \return a new DataSet
301 
302  \note For while, it only works if the spatial relation is te::gm::INTERSECTS
303  \note The caller will take the ownership of the returned pointer.
304  \note The returned DataSet will NOT share the intenal observations. It will clone the internal observations.
305  */
306  std::auto_ptr<DataSet> filter(const te::gm::Envelope* e, te::gm::SpatialRelation r) const;
307 
308  /*!
309  \brief It returns a new DataSet, based on a given spatial filter
310 
311  \param g A given geometry
312  \param r A given spatial relation.
313  \return a new DataSet
314 
315  \note For while, it only works if the spatial relation is te::gm::INTERSECTS
316  \note The caller will take the ownership of the returned pointer.
317  \note The returned DataSet will NOT share the intenal observations. It will clone the internal observations.
318  */
319  std::auto_ptr<DataSet> filter(const te::gm::Geometry* g, te::gm::SpatialRelation r) const;
320 
321  /*!
322  \brief It returns a new DataSet, based on a given temporal filter
323 
324  \param dt A given date time
325  \param tr A given temporal relation.
326 
327  \return a new DataSet
328 
329  \note The caller will take the ownership of the returned pointer.
330  \note The new DataSet will share the intenal observations.
331  */
332  std::auto_ptr<DataSet> filter(const te::dt::DateTime* dt, te::dt::TemporalRelation tr) const;
333 
334  /*!
335  \brief It returns a new DataSet, based on a given spatial and temporal filter
336 
337  \param e A given envelope
338  \param r A given spatial relation.
339  \param dt A given date time
340  \param tr A given temporal relation.
341 
342  \return a new DataSet
343 
344  \note The caller will take the ownership of the returned pointer.
345  \note The returned DataSet will NOT share the intenal observations. It will clone the internal observations.
346  */
347  std::auto_ptr<DataSet> filter(const te::gm::Envelope* e, te::gm::SpatialRelation r,
348  const te::dt::DateTime* dt, te::dt::TemporalRelation tr) const;
349 
350  /*!
351  \brief It returns a new DataSet, based on a given spatial filter
352 
353  \param g A given geometry
354  \param r A given spatial relation.
355  \param dt A given date time
356  \param tr A given temporal relation.
357 
358  \return a new DataSet
359 
360  \note The caller will take the ownership of the returned pointer.
361  \note The returned DataSet will NOT share the intenal observations. It will clone the internal observations.
362  */
363  std::auto_ptr<DataSet> filter(const te::gm::Geometry* g, te::gm::SpatialRelation r,
364  const te::dt::DateTime* dt, te::dt::TemporalRelation tr) const;
365 
366  /*!
367  \brief It returns the n nearest observations to a given date and time.
368 
369  \param dt A given date time
370  \param n The number of returned observations.
371 
372  \return a new DataSet
373 
374  \note The caller will take the ownership of the returned pointer.
375  \note The returned DataSet will share the intenal observations.
376  */
377  std::auto_ptr<te::stmem::DataSet> nearestObservations(const te::dt::DateTime* time, int n) const;
378 
379 
380  /*! \name DataSet inherited methods */
381  //@{
382  te::common::TraverseType getTraverseType() const;
383 
384  te::common::AccessPolicy getAccessPolicy() const;
385 
386  std::size_t getNumProperties() const;
387 
388  int getPropertyDataType(std::size_t i) const;
389 
390  std::string getPropertyName(std::size_t i) const;
391 
392  te::common::CharEncoding getPropertyCharEncoding(std::size_t i) const;
393 
394  std::string getDatasetNameOfProperty(std::size_t i) const;
395 
396  bool isEmpty() const;
397 
398  bool isConnected() const;
399 
400  std::size_t size() const;
401 
402  std::auto_ptr<te::gm::Envelope> getExtent(std::size_t i);
403 
404  bool moveNext();
405 
406  bool movePrevious();
407 
408  bool moveBeforeFirst();
409 
410  bool moveFirst();
411 
412  bool moveLast();
413 
414  bool move(std::size_t i);
415 
416  bool isAtBegin() const;
417 
418  bool isBeforeBegin() const;
419 
420  bool isAtEnd() const;
421 
422  bool isAfterEnd() const;
423 
424  char getChar(std::size_t i) const;
425 
426  unsigned char getUChar(std::size_t i) const;
427 
428  boost::int16_t getInt16(std::size_t i) const;
429 
430  boost::int32_t getInt32(std::size_t i) const;
431 
432  boost::int64_t getInt64(std::size_t i) const;
433 
434  bool getBool(std::size_t i) const;
435 
436  float getFloat(std::size_t i) const;
437 
438  double getDouble(std::size_t i) const;
439 
440  std::string getNumeric(std::size_t i) const;
441 
442  std::string getString(std::size_t i) const;
443 
444  std::auto_ptr<te::dt::ByteArray> getByteArray(std::size_t i) const;
445 
446  std::auto_ptr<te::gm::Geometry> getGeometry(std::size_t i) const;
447 
448  std::auto_ptr<te::rst::Raster> getRaster(std::size_t i) const;
449 
450  std::auto_ptr<te::dt::DateTime> getDateTime(std::size_t i) const;
451 
452  std::auto_ptr<te::dt::Array> getArray(std::size_t i) const;
453 
454  bool isNull(std::size_t i) const;
455 
456  std::auto_ptr<te::dt::AbstractData> getValue(std::size_t i) const;
457  //@}
458 
459  /*! \name Methods to set values to the DataSet
460 
461  \note These methods will take the ownership of the given pointers.
462  */
463  //@{
464  void setChar(std::size_t i, char value);
465 
466  void setChar(const std::string& name, char value);
467 
468  void setUChar(std::size_t i, unsigned char value);
469 
470  void setUChar(const std::string& name, unsigned char value);
471 
472  void setInt16(std::size_t i, boost::int16_t value);
473 
474  void setInt16(const std::string& name, boost::int16_t value);
475 
476  void setInt32(std::size_t i, boost::int32_t value);
477 
478  void setInt32(const std::string& name, boost::int32_t value);
479 
480  void setInt64(std::size_t i, boost::int64_t value);
481 
482  void setInt64(const std::string& name, boost::int64_t value);
483 
484  void setBool(std::size_t i, bool value);
485 
486  void setBool(const std::string& name, bool value);
487 
488  void setFloat(std::size_t i, float value);
489 
490  void setFloat(const std::string& name, float value);
491 
492  void setDouble(std::size_t i, double value);
493 
494  void setDouble(const std::string& name, double value);
495 
496  void setNumeric(std::size_t i, const std::string& value);
497 
498  void setNumeric(const std::string& name, const std::string& value);
499 
500  void setString(std::size_t i, const std::string& value);
501 
502  void setString(const std::string& name, const std::string& value);
503 
504  void setByteArray(std::size_t i, te::dt::ByteArray* value);
505 
506  void setByteArray(const std::string& name, te::dt::ByteArray* value);
507 
508  void setGeometry(std::size_t i, te::gm::Geometry* value);
509 
510  void setGeometry(const std::string& name, te::gm::Geometry* value);
511 
512  void setRaster(std::size_t i, te::rst::Raster* value);
513 
514  void setRaster(const std::string& name, te::rst::Raster* value);
515 
516  void setDateTime(std::size_t i, te::dt::DateTime* value);
517 
518  void setDateTime(const std::string& name, te::dt::DateTime* value);
519 
520  void setValue(std::size_t i, te::dt::AbstractData* value);
521 
522  void setValue(const std::string& name, te::dt::AbstractData* ad);
523  //@}
524 
525  protected:
526 
527  TimeToDataSetItemMap m_items; //!< The list of dataset items, ordered by time.
528  std::auto_ptr<te::sam::rtree::Index<te::mem::DataSetItem*> > m_RTree; //!< A RTree index created over the default geometry property
529  TimeToDataSetItemMap::const_iterator m_iterator; //!< The pointer to the current item.
530  bool m_beforeFirst; //! internal control
531  std::vector<std::string> m_pnames; //!< The list of property names.
532  std::vector<int> m_ptypes; //!< The list of property types.
533  std::map<int, te::common::CharEncoding> m_encodings; //!< The list of string properties char-encoding.
534  int m_begTimePropIdx; //!< The property index of the DataSetType that contains the phenomenon beginning time.
535  int m_endTimePropIdx; //!< The property index of the DataSetType that contains the phenomenon end time.
536  int m_geomPropIdx; //!< The property index of the DataSetType that contains geometries.
537  };
538  } // end namespace stmem
539 } // end namespace te
540 
541 #endif // __TERRALIB_STMEMORY_INTERNAL_DATASET_H
542 
543 
te::stmem::DateSetItemShrPtr
boost::shared_ptr< te::mem::DataSetItem > DateSetItemShrPtr
Definition: DataSet.h:49
te::common::CharEncoding
CharEncoding
Supported charsets (character encoding).
Definition: CharEncodingConv.h:45
te::da::DataSetType
A class that models the description of a dataset.
Definition: DataSetType.h:72
te::dt::TemporalRelation
TemporalRelation
Temporal relations between date and time (Source: Allen, 1991).
Definition: Enums.h:140
te::gm::SpatialRelation
SpatialRelation
Spatial relations between geometric objects.
Definition: Enums.h:127
te::stmem::DataSet::m_endTimePropIdx
int m_endTimePropIdx
The property index of the DataSetType that contains the phenomenon end time.
Definition: DataSet.h:535
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
TESTMEMORYEXPORT
#define TESTMEMORYEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:76
te::gm::Envelope
An Envelope defines a 2D rectangular region.
Definition: Envelope.h:51
te::rst::Raster
An abstract class for raster data strucutures.
Definition: Raster.h:71
te
URI C++ Library.
Definition: AddressGeocodingOp.h:51
te::stmem::TimeToDataSetItemMap
std::multimap< te::dt::DateTime *, DateSetItemShrPtr, te::dt::CompareDateTime > TimeToDataSetItemMap
Definition: DataSet.h:51
te::dt::AbstractData
A base class for values that can be retrieved from the data access module.
Definition: AbstractData.h:57
te::stmem::DataSet::m_begTimePropIdx
int m_begTimePropIdx
The property index of the DataSetType that contains the phenomenon beginning time.
Definition: DataSet.h:534
te::gm::Geometry
Geometry is the root class of the geometries hierarchy, it follows OGC and ISO standards.
Definition: Geometry.h:73
te::stmem::DataSet::m_iterator
TimeToDataSetItemMap::const_iterator m_iterator
The pointer to the current item.
Definition: DataSet.h:529
te::stmem::DataSet
Implementation of a in-memory data set that contains spatiotemporal observations indexed by time and ...
Definition: DataSet.h:61
te::mem::DataSetItem
An implementation of the DatasetItem class for the TerraLib In-Memory Data Access driver...
Definition: DataSetItem.h:56
te::da::DataSet
A dataset is the unit of information manipulated by the data access module of TerraLib.
Definition: DataSet.h:112
te::stmem::DataSet::m_ptypes
std::vector< int > m_ptypes
The list of property types.
Definition: DataSet.h:532
te::stmem::DataSet::m_encodings
std::map< int, te::common::CharEncoding > m_encodings
The list of string properties char-encoding.
Definition: DataSet.h:533
te::stmem::DataSet::m_items
TimeToDataSetItemMap m_items
The list of dataset items, ordered by time.
Definition: DataSet.h:527
te::stmem::DataSet::m_geomPropIdx
int m_geomPropIdx
The property index of the DataSetType that contains geometries.
Definition: DataSet.h:536
te::stmem::DataSet::m_RTree
std::auto_ptr< te::sam::rtree::Index< te::mem::DataSetItem * > > m_RTree
A RTree index created over the default geometry property.
Definition: DataSet.h:528
te::stmem::DataSet::m_pnames
std::vector< std::string > m_pnames
internal control
Definition: DataSet.h:531
te::dt::ByteArray
A class for representing binary data.
Definition: ByteArray.h:51
te::stmem::TimeAndDateSetItemPair
std::pair< te::dt::DateTime *, DateSetItemShrPtr > TimeAndDateSetItemPair
Definition: DataSet.h:50