DataSourceCatalog.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/datasource/DataSourceCatalog.h
22 
23  \brief It represents the system catalog of a DataSource.
24 */
25 
26 #ifndef __TERRALIB_DATAACCESS_INTERNAL_DATASOURCECATALOG_H
27 #define __TERRALIB_DATAACCESS_INTERNAL_DATASOURCECATALOG_H
28 
29 // TerraLib
30 #include "../Config.h"
31 #include "../dataset/DataSetType.h"
32 
33 // STL
34 #include <map>
35 #include <string>
36 #include <vector>
37 
38 // Boost
39 #include <boost/multi_index_container.hpp>
40 #include <boost/multi_index/mem_fun.hpp>
41 #include <boost/multi_index/ordered_index.hpp>
42 #include <boost/multi_index/random_access_index.hpp>
43 #include <boost/noncopyable.hpp>
44 
45 namespace te
46 {
47 // Forward declarations
48  namespace dt { class Property; }
49 
50  namespace da
51  {
52 // Forward declarations
53 
54  class DataSetType;
55  class ForeignKey;
56  class Sequence;
57  class DataSource;
58 
59  /*!
60  \class DataSourceCatalog
61 
62  \brief It represents the system catalog of a DataSource.
63 
64  \sa DataSource, Property, DataSetType, Sequence
65 
66  \ingroup dataaccess
67  */
68  class TEDATAACCESSEXPORT DataSourceCatalog : public boost::noncopyable
69  {
70  public:
71 
72  /** @name Basic Methods
73  * Basic methods for a DataSourceCatalog.
74  */
75  //@{
76 
77  /*! \brief It creates a new DataSourceCatalog. */
79 
80  /*! \brief Destructor. */
82 
83  /*!
84  \brief It returns the catalog identifier.
85 
86  \return A number that may be used to identify the catalog.
87 
88  \warning This value will be used by data source driver implementeers. So, don't rely on its value!
89  */
90  unsigned int getId() const;
91 
92  /*!
93  \brief It sets the catalog identifier.
94 
95  \param id A number that can be used to identify the catalog in its DataSource.
96 
97  \warning This value will be used by data source driver implementeers. So, don't
98  rely on its value nor call it if you are not implementing a data source!
99  */
100  void setId(unsigned int id);
101 
102  /*!
103  \brief It returns the DataSource associated to the catalog.
104 
105  \return The caller of this method will NOT take the ownership of the returned DataSource pointer.
106 
107  \note Every catalog that belongs to a DataSource will have an explicit association. If it has no parent, it doesn't belong to any store.
108  */
109  DataSource* getDataSource() const;
110 
111  /*!
112  \brief It sets the DataSource associated to the catalog.
113 
114  \param ds The DataSource to be associated to the catalog.
115 
116  \note Don't call this method in your code, it will be used by the driver developers!
117  */
118  void setDataSource(DataSource* ds);
119 
120  /*! \brief It clears the catalog, releasing all the resources used by it. */
121  void clear();
122 
123  //@}
124 
125  /** @name DataSetType Management Methods
126  * Methods for managing DataSetTypes.
127  */
128  //@{
129 
130  /*!
131  \brief It returns the number of datasets in the catalog.
132 
133  \return The number of datasets in the catalog.
134  */
135  std::size_t getNumberOfDataSets() const;
136 
137  /*!
138  \brief It checks if a dataset schema with the given name is in the catalog.
139 
140  \param name The dataset schema name to be cheked in the catalog.
141 
142  \return True if a dataset with the given name exists in the catalog.
143  */
144  bool datasetExists(const std::string& name) const;
145 
146  /*!
147  \brief It adds a new dataset schema to the catalog.
148 
149  \param dt The dataset schema to be added to the catalog.
150 
151  \pre The dt must not be associated to another catalog before calling this method.
152  \pre There is not a dataset schema in the catalog with the same name as dt.
153  \pre If the dataset schema has foreign keys the referenced schema must be already in the catalog.
154 
155  \post The dataset schema will be associated to the catalog.
156  \post The catalog will keep track of foreign keys and the referenced dataset schema.
157 
158  \exception Exception It throws an exception if the dataset schema can not be added.
159  */
160  void add(const DataSetTypePtr& dt);
161 
162  /*!
163  \brief It removes the dataset schema from the catalog.
164 
165  \param dt The dataset schema to be removed from the catalog.
166  \param cascade If true the method will remove also all objects that depends on the dataset schema (like sequences and foreign keys).
167 
168  \pre The dataset schema must be associated to the catalog.
169 
170  \post It will drop any association to the dataset schema or its attributes (like sequences and foreign keys) if casacade is true.
171  */
172  void remove(DataSetType* dt, const bool cascade = false);
173 
174  /*!
175  \brief It renames the dataset schema in the catalog.
176 
177  \param dt The dataset schema to be renamed.
178  \param newName The new name to be assigned to dt.
179 
180  \pre The dataset schema must be associated to the catalog.
181  \pre There is not a dataset schema in the catalog with the same value as newName.
182 
183  \post All internal indexes pointing to dt will be fixed and the dt will have newName set.
184 
185  \exception Exception It throws an exception if there is already
186  a dataset schema with the new name in the catalog, or if it
187  doesn't belong to the catalog.
188  */
189  void rename(DataSetType* dt, const std::string& newName);
190 
191  /*!
192  \brief It returns the i-th dataset schema.
193 
194  \param i The dataset schema index.
195 
196  \return The i-th dataset schema.
197 
198  \pre i must be in the range: [0, getNumberOfDataSets()).
199 
200  \note It doesn't check index range.
201  */
202  const DataSetTypePtr& getDataSetType(std::size_t i) const;
203 
204  /*!
205  \brief It searches for a dataset schema with the given name in the catalog.
206 
207  \param name The name of the searched dataset schema.
208 
209  \return A dataset schema with the given name or NULL if none is found.
210  */
211  const DataSetTypePtr& getDataSetType(const std::string& name) const;
212 
213  //@}
214 
215  /** @name Sequence Management Methods
216  * Methods for managing Sequences.
217  */
218  //@{
219 
220  /*!
221  \brief It returns the number of sequences in the catalog.
222 
223  \return The number of sequences in the catalog.
224  */
225  std::size_t getNumberOfSequences() const;
226 
227  /*!
228  \brief It adds a new sequence to the catalog.
229 
230  \param s The sequence to be added to the catalog.
231 
232 
233  \pre The sequence must not be associated to a catalog before calling this method.
234  \pre There is not a sequence in the catalog with the same name as the sequence to be added.
235  \pre There is not a sequence in the catalog with the same id as the sequence to be added.
236  \pre If the sequence is owned by a given DataSetType property, the DataSetType must already be in the catalog.
237 
238  \post The sequence will have the catalog associated to it.
239  \post The catalog will take the ownership of the informed sequence.
240 
241  \exception Exception It throws an exception if the sequence can not be added.
242  \exception Exception It throws an exception if the sequence is owned by a given DataSetType property and this DataSetType is not in the catalog.
243  */
244  void add(Sequence* s);
245 
246  /*!
247  \brief It removes the sequence from the catalog.
248 
249  \param s The sequence to be removed from the catalog.
250 
251  \pre The sequence must associated to the catalog.
252 
253  \post The s pointer will be invalidated.
254  */
255  void remove(Sequence* s);
256 
257  /*!
258  \brief It will detaches the Sequence from the catalog.
259 
260  \param s The Sequence to be detached from the catalog.
261 
262  \pre The Sequence must associated to the catalog.
263 
264  \post It will drop any association to the Sequence.
265  \post The caller of this method will take the ownership of s pointer.
266  */
267  void detach(Sequence* s);
268 
269  /*!
270  \brief It returns the i-th Sequence.
271 
272  \param i The Sequence index.
273 
274  \return The i-th Sequence.
275 
276  \pre i must be in the range of [0, getNumberOfSequences()).
277 
278  \note The caller will not take the ownership of the returned Sequence.
279  \note It doesn't check the index range.
280  */
281  Sequence* getSequence(std::size_t i) const;
282 
283  /*!
284  \brief It searches for a Sequence with the given name in the catalog.
285 
286  \param name The name of the searched Sequence.
287 
288  \return A Sequence with the given name, or NULL if none is found.
289 
290  \note The caller will not take the ownership of the returned Sequence.
291  */
292  Sequence* getSequence(const std::string& name) const;
293 
294  //@}
295 
296  /** @name Helper Methods
297  * Methods used to keep the associations among catalog's objects.
298  */
299  //@{
300 
301  /*!
302  \brief It checks if the referenced DataSetType is in the catalog and associate the fk to it.
303 
304  \param fk The foreign key to keep the association.
305 
306  \pre The DataSetType referenced by the fk must be in the catalog.
307  \pre The foreign key must not have been associated before.
308 
309  \post If the DataSetType referenced by the foreign key is in the catalog, it will have an association in the catalog.
310 
311  \exception It throws an exception if the referenced DataSetType is not in the DataSourceCatalog.
312  */
313  void addRef(ForeignKey* fk);
314 
315  /*!
316  \brief It drops the reference between the foreign key and its referenced DataSetType.
317 
318  \param fk The foreign key to remove the association from the catalog.
319 
320  \pre The DataSetType referenced by the fk must be in the catalog.
321  \pre The foreign key must have been associated before.
322 
323  \post The association between the DataSetType and the foreign key will be removed.
324 
325  \exception It throws an exception if the referenced DataSetType is not in the DataSourceCatalog.
326  */
327  void removeRef(ForeignKey* fk);
328 
329  /*!
330  \brief It returns the list of fk referencing the given DataSetType in the catalog.
331 
332  \param dt The DataSetType we are searching for foreign keys referencing it.
333 
334  \return The list of fk referencing the given DataSetType as a range defined over a pair of iterators.
335 
336  \note In the returned iterator, the second component is the end special mark.
337  */
338  std::pair<std::multimap<DataSetType*, ForeignKey*>::const_iterator,
339  std::multimap<DataSetType*, ForeignKey*>::const_iterator>
340  getRefFK(DataSetType* dt) const { return m_dependentFkIdx.equal_range(dt); }
341 
342  /*!
343  \brief It drops Sequences that depends on the property.
344 
345  \param p A Property that may owns a sequence in the catalog.
346 
347  \post All Sequences referencing p will be dropped (released).
348  */
349  void dropDependentSequences(te::dt::Property* p);
350 
351  //@}
352 
353  protected:
354 
355  /** @name Helper Methods for Sequences
356  * Methods used in the internals of DataSourceCatalog to manage Sequences.
357  */
358  //@{
359 
360  /*!
361  \brief It checks if the Sequence is owned by a DataSetType property and if that DataSetType is in the catalog.
362 
363  \param s The Sequence we are checking the dependency of a FetaureType.
364 
365  \exception Exception It throws an exception if the sequence is owned by a
366  FetaureType that is not in the catalog nor could be determined.
367  */
368  void checkSequenceDependency(Sequence* s) const;
369 
370  /*!
371  \brief It looks if the sequence is owned by a given DataSetType property and insert this information into the sequence depency index.
372 
373  \param s The sequence we want to index owner information.
374 
375  \pre If the sequence is owned, the associated DataSetType is already in the catalog.
376 
377  \post If the sequence s is owned it will have an index entry to the referred DataSetType.
378 
379  \exception Exception It throws an exception if the sequence is owned by a
380  FetaureType that is not in the catalog nor could be determined.
381  */
382  void indexSequenceDependency(Sequence* s);
383 
384  /*!
385  \brief It drops Sequences that depends on the DataSetType dt.
386 
387  \param dt A DataSetType that belongs to the catalog.
388 
389  \post All Sequences referencing dt will be dropped (released).
390  */
391  void dropDependentSequences(DataSetType* dt);
392 
393  /*!
394  \brief It drops the Sequence entry in the DataSetType sequence dependency list.
395 
396  \param s A Sequence to be removed from the list of dependency.
397 
398  \post The entry pointing to the Sequence will be dropped (released).
399 
400  \exception Exception It throws an exception if the sequence is owned by a dt and it is not in the catalog.
401  */
402  void dropDependentSequenceEntry(Sequence* s);
403 
404  //@}
405 
406  /** @name Helper Methods for Foreign Keys
407  * Methods used in the internals of DataSourceCatalog to manage Foreign Keys.
408  */
409  //@{
410 
411  /*!
412  \brief It checks if the DataSetTypes referenced by dt's foreign keys are in the catalog.
413 
414  \param dt The DataSetType we are checking the foreign key dependency is ok.
415 
416  \exception Exception It throws an exception if one of the foreign key
417  has a referenced FetaureType that is not in the catalog.
418  */
419  void checkFKsDependency(DataSetType* dt) const;
420 
421  /*!
422  \brief It looks for foreign keys in the DataSetType dt and try to index then with respect to referenced DataSetTypes.
423 
424  \param dt The DataSetType whose foreign keys will be indexed.
425 
426  \pre All DataSetTypes referenced by dt foreign keys must be in the catalog.
427  \pre The foreign keys of dt must not have be indexed before.
428 
429  \post If the DataSetType dt has foreign keys they will have an index entry to the referred DataSetType.
430  */
431  void indexFKs(DataSetType* dt);
432 
433  /*!
434  \brief It drops foreign keys from other DataSetTypes that depends on the attributes in the given DataSetType dt.
435 
436  \param dt A DataSetType that belongs to the catalog.
437 
438  \post All DataSetTypes foreign keys referencing dt will be dropped (released).
439  */
440  void dropDependentFKs(DataSetType* dt);
441 
442  //@}
443 
444  private:
445 
447  {
448  typedef std::string result_type;
449 
450  result_type operator()(const DataSetTypePtr& dt) const;
451  };
452 
453  typedef boost::multi_index::multi_index_container<
455  boost::multi_index::indexed_by<
456  boost::multi_index::ordered_unique<dataset_name_cmp>,
457  boost::multi_index::random_access<>
458  >
460 
462  {
463  typedef std::string result_type;
464 
465  result_type operator()(const Sequence* const s) const;
466  };
467 
468  typedef boost::multi_index::multi_index_container<
469  Sequence*,
470  boost::multi_index::indexed_by<
471  boost::multi_index::ordered_unique<sequence_name_cmp>,
472  boost::multi_index::random_access<>
473  >
475 
476 // DataSetType objects
478 
479 // Sequence objects
481 
482  std::multimap<DataSetType*, sequence_idx_type::iterator> m_seqFTIdx; //!< A multimap : owner-dt -> sequence-it.
483 
484 // Foreign-key objects
485  std::multimap<DataSetType*, ForeignKey*> m_dependentFkIdx; //!< A multimap : datasettype -> fk. It tells for a DataSetType the list of fk referencing it.
486 
487  unsigned int m_id; //!< An identification number inside the DataSource.
488  DataSource* m_ds; //!< The DataSource associated to the Catalog.
489 
490  static DataSetTypePtr sm_nullds;
491  };
492 
493  typedef boost::shared_ptr<DataSourceCatalog> DataSourceCatalogPtr;
494 
495  inline unsigned int DataSourceCatalog::getId() const
496  {
497  return m_id;
498  }
499 
500  inline void DataSourceCatalog::setId(unsigned int id)
501  {
502  m_id = id;
503  }
504 
506  {
507  return m_ds;
508  }
509 
511  {
512  m_ds = ds;
513  }
514 
515  inline std::size_t DataSourceCatalog::getNumberOfDataSets() const
516  {
517  return m_datasets.size();
518  }
519 
520  inline std::size_t DataSourceCatalog::getNumberOfSequences() const
521  {
522  return m_sequences.size();
523  }
524 
525  } // end namespace da
526 } // end namespace te
527 
528 
529 #endif // __TERRALIB_DATAACCESS_INTERNAL_DATASOURCECATALOG_H
530 
531 
void setDataSource(DataSource *ds)
It sets the DataSource associated to the catalog.
std::multimap< DataSetType *, ForeignKey * > m_dependentFkIdx
A multimap : datasettype -> fk. It tells for a DataSetType the list of fk referencing it...
static DataSetTypePtr sm_nullds
boost::shared_ptr< DataSetType > DataSetTypePtr
Definition: DataSetType.h:653
It represents the system catalog of a DataSource.
A class that models the description of a dataset.
Definition: DataSetType.h:72
It describes a sequence (a number generator).
Definition: Sequence.h:56
std::size_t getNumberOfDataSets() const
It returns the number of datasets in the catalog.
An abstract class for data providers like a DBMS, Web Services or a regular file. ...
Definition: DataSource.h:119
It models a property definition.
Definition: Property.h:59
boost::multi_index::multi_index_container< Sequence *, boost::multi_index::indexed_by< boost::multi_index::ordered_unique< sequence_name_cmp >, boost::multi_index::random_access<> > > sequence_idx_type
DataSource * getDataSource() const
It returns the DataSource associated to the catalog.
boost::multi_index::multi_index_container< DataSetTypePtr, boost::multi_index::indexed_by< boost::multi_index::ordered_unique< dataset_name_cmp >, boost::multi_index::random_access<> > > dataset_idx_type
boost::shared_ptr< DataSourceCatalog > DataSourceCatalogPtr
unsigned int getId() const
It returns the catalog identifier.
DataSource * m_ds
The DataSource associated to the Catalog.
std::multimap< DataSetType *, sequence_idx_type::iterator > m_seqFTIdx
A multimap : owner-dt -> sequence-it.
URI C++ Library.
It models a foreign key constraint for a DataSetType.
Definition: ForeignKey.h:50
unsigned int m_id
An identification number inside the DataSource.
std::size_t getNumberOfSequences() const
It returns the number of sequences in the catalog.
#define TEDATAACCESSEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:97
sequence_idx_type m_sequences
void setId(unsigned int id)
It sets the catalog identifier.
std::pair< std::multimap< DataSetType *, ForeignKey * >::const_iterator, std::multimap< DataSetType *, ForeignKey * >::const_iterator > getRefFK(DataSetType *dt) const
It returns the list of fk referencing the given DataSetType in the catalog.