DataSourceTransactor.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/DataSourceTransactor.h
22 
23  \brief A DataSourceTransactor can be viewed as a connection to the data source for reading/writing things into it.
24 */
25 
26 #ifndef __TERRALIB_DATAACCESS_INTERNAL_DATASOURCETRANSACTOR_H
27 #define __TERRALIB_DATAACCESS_INTERNAL_DATASOURCETRANSACTOR_H
28 
29 // TerraLib
30 #include "../../common/Enums.h"
31 #include "../../geometry/Enums.h"
32 #include "../dataset/CheckConstraint.h"
33 #include "../dataset/DataSetType.h"
34 #include "../dataset/DataSet.h"
35 #include "../dataset/ForeignKey.h"
36 #include "../dataset/Index.h"
37 #include "../dataset/PrimaryKey.h"
38 #include "../dataset/Sequence.h"
39 #include "../dataset/UniqueKey.h"
40 #include "../Config.h"
41 #include "BatchExecutor.h"
42 #include "PreparedQuery.h"
43 
44 // STL
45 #include <map>
46 #include <memory>
47 #include <string>
48 #include <vector>
49 #include <set>
50 
51 // Boost
52 #include <boost/ptr_container/ptr_vector.hpp>
53 #include <boost/cstdint.hpp>
54 #include <boost/noncopyable.hpp>
55 #include <boost/shared_ptr.hpp>
56 
57 
58 namespace te
59 {
60  // Forward declarations
61  namespace dt { class Property; }
62  namespace gm { class Envelope; class Geometry; }
63 
64  namespace da
65  {
66  // Forward declarations
67  class DataSetTypeCapabilities;
68  class DataSource;
69  class ObjectIdSet;
70  class Query;
71  class Select;
72 
73  /*!
74  \class DataSourceTransactor
75 
76  \brief A DataSourceTransactor can be viewed as a connection to the data source for reading/writing things into it.
77 
78  A transactor can be used to create a transaction, a prepared query or a batch command executor.
79 
80  If you are planning a multi-thread application, it is better not to share
81  the same transactor between threads because its methods are not thread-safe. Instead,
82  use one transactor per thread.
83 
84  \ingroup dataaccess
85 
86  \sa DataSource, DataSet, Query, PreparedQuery, BatchExecutor
87  */
88  class TEDATAACCESSEXPORT DataSourceTransactor : public boost::noncopyable
89  {
90  public:
91 
92  /*! \brief Default constructor that can be called by subclasses. */
94 
95  /*! \brief Virtual destructor. */
96  virtual ~DataSourceTransactor();
97 
98  /*!
99  \brief It returns the parent data source of the transactor.
100  */
101  virtual DataSource* getDataSource() const = 0;
102 
103  /** @name Transaction
104  * Methods for dealing with transactions.
105  */
106  //@{
107 
108  /*!
109  \brief It starts a new transaction.
110 
111  \note Not thread-safe!
112  */
113  virtual void begin() = 0;
114 
115  /*!
116  \brief It commits the transaction.
117 
118  After commiting or rolling back, you can start another transaction.
119 
120  \note Not thread-safe!
121  */
122  virtual void commit() = 0;
123 
124  /*!
125  \brief It aborts the transaction. Any changes will be rolled-back.
126 
127  After commiting or rolling back, you can start another transaction.
128 
129  \note Not thread-safe!
130  */
131  virtual void rollBack() = 0;
132 
133  /*!
134  \brief It returns true if a transaction is in progress, otherwise, it returns false.
135 
136  \return True, if a transaction is in progress, otherwise, false.
137  */
138  virtual bool isInTransaction() const = 0;
139  //@}
140 
141  /** @name DataSet Retrieval
142  * Methods for retrieving data from the data source.
143  */
144  //@{
145 
146  /*!
147  \brief It gets the dataset identified by the given name.
148  A dataset can be connected or disconnected. A connected dataset, after its creation through
149  the data source transactor, continues to depend on the connection given by its associated
150  data source. Differently, a disconnected dataset, after its creation, no more depends of the
151  connection given by the data source, and it continues to live after the connection has been
152  released to the data source.
153 
154  \param name The dataset name.
155  \param accessPolicy Access policy.
156  \param travType The traverse type associated to the returned dataset.
157  \param connected A flag to indicate if the returned dataset is connected or not.
158 
159  \exception Exception It can throw an exception if:
160  <ul>
161  <li>something goes wrong during the data retrieval</li>
162  <li>if the data source driver doesn't support the traversal type</li>
163  </ul>
164 
165  \note Not thread-safe!
166  */
167  virtual std::auto_ptr<DataSet> getDataSet(const std::string& name,
169  bool connected = false,
170  const te::common::AccessPolicy accessPolicy = te::common::RAccess) = 0;
171 
172  /*!
173  \brief It gets the dataset identified by the given name using a spatial filter over the specified property.
174  A dataset can be connected or disconnected. A connected dataset, after its creation through
175  the data source transactor, continues to depend on the connection given by its associated
176  data source. Differently, a disconnected dataset, after its creation, no more depends of the
177  connection given by the data source, and it continues to live after the connection has been
178  released to the data source.
179 
180  \param name The dataset name.
181  \param propertyName The name of the spatial property that will be used to apply the spatial filter.
182  \param e A rectangle to be used as a spatial filter when retrieving datasets.
183  \param r The spatial relation to be used during the filter.
184  \param accessPolicy Access policy.
185  \param travType The traversal type associated to the returned dataset.
186  \param connected A flag to indicate if the returned dataset is connected or not.
187 
188  \exception Exception It can throw an exception if:
189  <ul>
190  <li>something goes wrong during the data retrieval</li>
191  <li>if the data source driver doesn't support the traversal type</li>
192  </ul>
193 
194  \note The envelope coordinates should be in the same coordinate system as the dataset.
195 
196  \note Not thread-safe!
197  */
198  virtual std::auto_ptr<DataSet> getDataSet(const std::string& name,
199  const std::string& propertyName,
200  const te::gm::Envelope* e,
203  bool connected = false,
204  const te::common::AccessPolicy accessPolicy = te::common::RAccess) = 0;
205 
206  /*!
207  \brief It gets the dataset identified by the given name using a spatial filter over the given geometric property.
208  A dataset can be connected or disconnected. A connected dataset, after its creation through
209  the data source transactor, continues to depend on the connection given by its associated
210  data source. Differently, a disconnected dataset, after its creation, no more depends of the
211  connection given by the data source, and it continues to live after the connection has been
212  released to the data source.
213 
214  \param name The dataset name.
215  \param propertyName The name of the spatial property that will be used to apply the spatial filter.
216  \param g The geometry that will be used as a spatial filter when retrieving the dataset.
217  \param r The spatial relation that will be used during the filtering.
218  \param accessPolicy Access policy.
219  \param travType The traverse type associated to the returned dataset.
220  \param connected A flag to indicate if the returned dataset is connected or not.
221 
222  \exception Exception It can throw an exception if:
223  <ul>
224  <li>something goes wrong during the data retrieval</li>
225  <li>if the data source driver doesn't support the traversal type</li>
226  </ul>
227 
228  \note The geometry coordinates should be in the same coordinate system as the dataset.
229 
230  \note Not thread-safe!
231  */
232  virtual std::auto_ptr<DataSet> getDataSet(const std::string& name,
233  const std::string& propertyName,
234  const te::gm::Geometry* g,
237  bool connected = false,
238  const te::common::AccessPolicy accessPolicy = te::common::RAccess) = 0;
239 
240  /*!
241  \brief It gets the dataset identified by the given name using the set of objects identification.
242  A dataset can be connected or disconnected. A connected dataset, after its creation through
243  the data source transactor, continues to depend on the connection given by its associated
244  data source. Differently, a disconnected dataset, after its creation, no more depends of the
245  connection given by the data source, and it continues to live after the connection has been
246  released to the data source.
247 
248  \param name The dataset name of the dataset.
249  \param oids A pointer for the set of objects. Do not pass null, nor an empty set.
250  \param accessPolicy Access policy.
251  \param travType The traverse type associated to the returned dataset.
252  \param connected A flag to indicate if the returned dataset is connected or not.
253 
254  \exception Exception It can throw an exception if:
255  <ul>
256  <li>something goes wrong during data retrieval</li>
257  <li>if the data source driver doesn't support the traversal type</li>
258  </ul>
259  */
260  std::auto_ptr<te::da::DataSet> getDataSet(const std::string& name,
261  const ObjectIdSet* oids,
263  bool connected = false,
264  const te::common::AccessPolicy accessPolicy = te::common::RAccess);
265 
266  /*!
267  \brief It executes a query that may return some data using a generic query.
268  A dataset can be connected or disconnected. A connected dataset, after its creation through
269  the data source transactor, continues to depend on the connection given by its associated
270  data source. Differently, a disconnected dataset, after its creation, no more depends of the
271  connection given by the data source, and it continues to live after the connection has been
272  released to the data source.
273  This method is different of the method that accepts a dataset name and
274  a spatial filter, because it allows the retrieving of only a
275  subset of the attributes, since a query can include a property list.
276 
277  \exception Exception It can throw an exception if:
278  <ul>
279  <li>something goes wrong during the data retrieval</li>
280  <li>if the data source driver doesn't support the traversal type</li>
281  </ul>
282 
283  \param q A valid query object.
284  \param travType The traverse type associated to the returned dataset.
285  \param connected A flag to indicate if the returned dataset is connected or not.
286  \param accessPolicy Access policy.
287 
288  \note Not thread-safe!
289  */
290  virtual std::auto_ptr<DataSet> query(const Select& q,
292  bool connected = false,
293  const te::common::AccessPolicy accessPolicy = te::common::RAccess) = 0;
294 
295  /*!
296  \brief It executes a query that may return some data using the data source native language.
297  A dataset can be connected or disconnected. A connected dataset, after its creation through
298  the data source transactor, continues to depend on the connection given by its associated
299  data source. Differently, a disconnected dataset, after its creation, no more depends of the
300  connection given by the data source, and it continues to live after the connection has been
301  released to the data source.
302 
303  \param query A query string in the data source native language.
304  \param travType The traverse type associated to the returned dataset.
305  \param connected A flag to indicate if the returned dataset is connected or not.
306  \param accessPolicy Access policy.
307 
308  \exception Exception It can throw an exception if:
309  <ul>
310  <li>something goes wrong during the data retrieval</li>
311  <li>if the data source driver doesn't support the traversal type</li>
312  </ul>
313 
314  \note Don't use this method, if you want portability for your application.
315 
316  \note Not thread-safe!
317  */
318  virtual std::auto_ptr<DataSet> query(const std::string& query,
320  bool connected = false,
321  const te::common::AccessPolicy accessPolicy = te::common::RAccess) = 0;
322  //@}
323 
324  /** @name Command Execution Methods
325 
326  * Methods for executing commands against the data source.
327  */
328  //@{
329 
330  /*!
331  \brief It executes the specified command using a generic query representation.
332 
333  \param command A query like: CREATE, DROP, ALTER, INSERT, UPDATE, DELETE.
334 
335  \exception Exception It can throw an exception, if the query cannot be performed.
336 
337  \note Not thread-safe!
338  */
339  virtual void execute(const Query& command) = 0;
340 
341  /*!
342  \brief It executes the specifed command in the data source native language.
343 
344  \param command A query string in the data source native language (like: CREATE, DROP, ALTER, INSERT, UPDATE, DELETE).
345 
346  \exception Exception It can throw an exception, if the query cannot be performed.
347 
348  \note Not thread-safe!
349  */
350  virtual void execute(const std::string& command) = 0;
351  //@}
352 
353  /** @name Fine Grained Transactor Objects
354  * Methods for retrieving fine-grained transactor objects.
355  */
356  //@{
357  /*!
358  \brief It creates a prepared query object that may be used for query commands (select, insert, update and delete) that are used repeatedly.
359 
360  \param qName The prepared query name.
361 
362  \exception Exception An exception can be thrown if the prepared query cannot be performed.
363 
364  \return A prepared query object owned by the caller.
365  */
366  virtual std::auto_ptr<PreparedQuery> getPrepared(const std::string& qName = std::string("")) = 0;
367 
368  /*!
369  \brief It creates a batch command executor.
370 
371  \exception Exception An exception can be thrown if the batch command executor cannot be performed.
372 
373  \return A batch command executor owned by the caller.
374  */
375  virtual std::auto_ptr<BatchExecutor> getBatchExecutor() = 0;
376  //@}
377 
378  /** @name Auxiliary Commands for Commands and Queries
379  * Auxiliary methods for commands and queries.
380  */
381  //@{
382 
383  /*!
384  \brief It requests that the data source stop the processing of the current command.
385 
386  \note Not thread-safe!
387  */
388  virtual void cancel() = 0;
389 
390  /*!
391  \brief It returns the last id generated by an insertion command.
392 
393  \return The last id generated by an insertion command.
394 
395  \note This is the way to deal with auto-increment values.
396 
397  \note Not thread-safe!
398  */
399  virtual boost::int64_t getLastGeneratedId() = 0;
400 
401  /*!
402  \brief It escapes a string for using in commands and queries.
403 
404  \param value Any string.
405 
406  \return A valid escaped string.
407 
408  \note Not thread-safe!
409  */
410  virtual std::string escape(const std::string& value) = 0;
411 
412  /*!
413  \brief It returns true if the given string is a valid dataset name.
414 
415  \param datasetName A dataset name whose validity will be checked.
416 
417  \return True, if the name is valid according to the data source rules.
418 
419  \note Not thread-safe!
420  */
421  virtual bool isDataSetNameValid(const std::string& datasetName);
422 
423  /*!
424  \brief It checks if the given property name is valid.
425 
426  \param propertyName A property name whose validity will be checked.
427 
428  \return True, if the name is valid according to the data source rules.
429 
430  \note Not thread-safe!
431  */
432  virtual bool isPropertyNameValid(const std::string& propertyName);
433  //@}
434 
435  /** @name Dataset Metadata Retrieval
436  * Methods for retrieving metadata about the datasets of the data source.
437  */
438  //@{
439 
440  /*!
441  \brief It It gets the dataset names available in the data source.
442 
443  \return The dataset names available in the data source.
444 
445  \exception Exception An exception can be thrown, if the dataset names could not be retrieved.
446 
447  \note Each dataset in the data source must have a unique name. For example, in a DBMS the name
448  may contain the schema name before the table name separated by a dot notation (".").
449 
450  \note Not thread-safe!
451  */
452  virtual std::vector<std::string> getDataSetNames() = 0;
453 
454  /*!
455  \brief It retrieves the number of data sets available in the data source.
456 
457  \exception Exception An exception can be thrown, if the number of datasets could not be retrieved.
458 
459  \return The number of data sets available in the data source.
460 
461  \note Not thread-safe!
462  */
463  virtual std::size_t getNumberOfDataSets() = 0;
464 
465  /*!
466  \brief It gets information about the given dataset.
467 
468  This method can provide the following information about a dataset:
469  <ul>
470  <li>the list of properties, including: name, data type, size, if the value is required or not, if it is an autoincrement</li>
471  <li>primary key</li>
472  <li>foreign keys</li>
473  <li>unique keys</li>
474  <li>check constraints</li>
475  <li>indexes</li>
476  </ul>
477 
478  \param name The name of the dataset we are looking information for.
479 
480  \exception Exception An exception can be thrown, if the information about the dataset could not be retrieved.
481 
482  \return The dataset schema.
483 
484  \note Not thread-safe!
485  */
486  virtual std::auto_ptr<te::da::DataSetType> getDataSetType(const std::string& name) = 0;
487 
488  /*!
489  \brief It gets capabilities about a data set.
490 
491  \param name Name of the dataset.
492 
493  \return The capabilities of the data set.
494 
495  \note By default it returns a fully support capabilities. If a driver does not support any capabilty, it may reimplement this function.
496  */
497  virtual std::auto_ptr<te::da::DataSetTypeCapabilities> getCapabilities(const std::string& name);
498 
499  /*!
500  \brief It retrieves the properties of the dataset.
501 
502  \param datasetName The dataset name.
503 
504  \exception Exception An exception can be thrown, if the dataset properties could not be retrieved.
505 
506  \return The properties of the dataset.
507 
508  \note Not thread-safe!
509  */
510  virtual boost::ptr_vector<te::dt::Property> getProperties(const std::string& datasetName) = 0;
511 
512  /*!
513  \brief It retrieves the property with the given name from the dataset.
514 
515  \param datasetName The dataset name.
516  \param propertyName The property name.
517 
518  \exception Exception An exception can be thrown, if the dataset property could not be retrieved.
519 
520  \return The property with the given name from the dataset.
521 
522  \note Not thread-safe!
523  */
524  virtual std::auto_ptr<te::dt::Property> getProperty(const std::string& datasetName, const std::string& name) = 0;
525 
526  /*!
527  \brief It retrieves the property lying in the given position from the dataset.
528 
529  \param datasetName The dataset name.
530  \param propertyPos The property position.
531 
532  \exception Exception An exception can be thrown, if the property lying in the given position could not be retrieved.
533 
534  \return The property in the given position.
535 
536  \note Not thread-safe!
537  */
538  virtual std::auto_ptr<te::dt::Property> getProperty(const std::string& datasetName, std::size_t propertyPos) = 0;
539 
540  /*!
541  \brief It gets the property names of the given dataset.
542 
543  \param datasetName The dataset name.
544 
545  \exception Exception An exception can be thrown, if the property names of the dataset could not be retrieved.
546 
547  \return The property names of the dataset.
548 
549  \note Each dataset in the data source must have a unique name. For example, in a DBMS the name
550  may contain the schema name before the table name separated by a dot notation (".").
551 
552  \note Not thread-safe!
553  */
554  virtual std::vector<std::string> getPropertyNames(const std::string& datasetName) = 0;
555 
556  /*!
557  \brief It gets the number of properties of the given dataset.
558 
559  \param datasetName The dataset name.
560 
561  \exception Exception An exception can be thrown, if the number of dataset properties could not be retrieved.
562 
563  \return The number of properties of the given dataset.
564 
565  \note Not thread-safe!
566  */
567  virtual std::size_t getNumberOfProperties(const std::string& datasetName) = 0;
568 
569  /*!
570  \brief It checks if a property with the given name exists in the dataset.
571 
572  \param datasetName The dataset name.
573  \param name The property name.
574 
575  \exception Exception An exception can be thrown, if the existence of the dataset property could not be obtained.
576 
577  \return True, if the property exists in the dataset; otherwise, it returns false.
578 
579  \note Not thread-safe!
580  */
581  virtual bool propertyExists(const std::string& datasetName, const std::string& name) = 0;
582 
583  /*!
584  \brief It adds a new property to the dataset schema.
585 
586  \param datasetName The dataset where the property will be added.
587  \param p The new property to be added.
588 
589  \exception Exception An exception can be thrown, if the property could not be added to the dataset schema.
590 
591  \note Don't delete the given property, because the schema will take the ownership of it.
592  \note Not thread-safe!
593  */
594  virtual void addProperty(const std::string& datasetName, te::dt::Property* p) = 0;
595 
596  /*!
597  \brief It removes a property from the given dataset.
598 
599  \param datasetName The dataset from where the given property will be removed.
600  \param name The property to be removed from the dataset.
601 
602  \exception Exception An exception can be thrown, if the dataset property could not be removed.
603 
604  \note Not thread-safe!
605  */
606  virtual void dropProperty(const std::string& datasetName, const std::string& name) = 0;
607 
608  /*!
609  \brief It renames a property of the given dataset.
610 
611  \param datasetName The dataset containig the property to be renamed.
612  \param propertyName The property to be renamed from the dataset.
613  \param newPropertyName The new property name.
614 
615  \exception Exception An exception can be thrown, if the dataset property could not be renamed.
616 
617  \note Not thread-safe!
618  */
619  virtual void renameProperty(const std::string& datasetName,
620  const std::string& propertyName,
621  const std::string& newPropertyName) = 0;
622 
623  virtual void changePropertyDefinition(const std::string& datasetName, const std::string& propName, te::dt::Property* newProp);
624 
625  /*!
626  \brief It retrieves the primary key of the dataset.
627 
628  \param datasetName The dataset name.
629 
630  \exception Exception An exception can be thrown, if the primary key could not be retrieved.
631 
632  \return If a primary key exists in the dataset, it is returned; otherwise, a NULL is returned.
633 
634  \note Not thread-safe!
635  */
636  virtual std::auto_ptr<te::da::PrimaryKey> getPrimaryKey(const std::string& datasetName) = 0;
637 
638  /*!
639  \brief It checks if a primary key exists in the dataset.
640 
641  \param datasetName The dataset name.
642  \param name The primary key name.
643 
644  \exception Exception An exception can be thrown, if the existence of the primary key could not be determined.
645 
646  \return True, if a primary key exists in the dataset; otherwise, it returns false.
647 
648  \note Not thread-safe!
649  */
650  virtual bool primaryKeyExists(const std::string& datasetName, const std::string& name) = 0;
651 
652  /*!
653  \brief It adds a primary key constraint to the dataset schema.
654 
655  \param datasetName The name of the dataset where the primary key will be added.
656  \param pk The primary key constraint.
657 
658  \exception Exception An exception can be thrown, if the primary key could not be added to the dataset schema.
659 
660  \note Don't delete the given primary key, because the schema will take the ownership of it.
661  \note Not thread-safe!
662  */
663  virtual void addPrimaryKey(const std::string& datasetName, PrimaryKey* pk) = 0;
664 
665  /*!
666  \brief It removes the primary key constraint from the dataset schema.
667 
668  \param datasetName The dataset from where the primary key will be removed.
669 
670  \exception Exception An exception can be thrown, if the primary key could not be dropped from the dataset schema.
671 
672  \note Not thread-safe!
673  */
674  virtual void dropPrimaryKey(const std::string& datasetName) = 0;
675 
676  /*!
677  \brief It retrieves the foreign key from the given dataset.
678 
679  \param datasetName The dataset name.
680  \param name The foreign key name.
681 
682  \exception Exception An exception can be thrown, if the foreign key could not be retrieved.
683 
684  \return If the foreign key exists in the dataset, it is returned; otherwise, a NULL is returned.
685 
686  \note Not thread-safe!
687  */
688  virtual std::auto_ptr<ForeignKey> getForeignKey(const std::string& datasetName, const std::string& name) = 0;
689 
690  /*!
691  \brief It gets the foreign key names of the given dataset.
692 
693  \param datasetName The dataset name.
694 
695  \exception Exception An exception can be thrown, if the foreign key names could not be retrieved.
696 
697  \return The foreign key names of the given dataset.
698 
699  \note Not thread-safe!
700  */
701  virtual std::vector<std::string> getForeignKeyNames(const std::string& datasetName) = 0;
702 
703  /*!
704  \brief It checks if a foreign key with the given name exists in the data source.
705 
706  \param datasetName The dataset name.
707  \param name The foreign key name.
708 
709  \exception Exception An exception can be thrown, if the existence of the foreign key could not be obtained.
710 
711  \return True, if the foreign key exists in the dataset; otherwise, it returns false.
712  */
713  virtual bool foreignKeyExists(const std::string& datasetName, const std::string& name) = 0;
714 
715  /*!
716  \brief It adds a foreign key constraint to a dataset.
717 
718  \param datasetName The dataset where the foreign key constraint will be added.
719  \param fk The foreign key constraint.
720 
721  \exception Exception An exception can be thrown, if the foreign key could not be added to the dataset schema.
722 
723  \note Don't delete the given foreign key, because the schema will take the ownership of it.
724  \note Not thread-safe!
725  */
726  virtual void addForeignKey(const std::string& datasetName, ForeignKey* fk) = 0;
727 
728  /*!
729  \brief It removes the foreign key constraint from the dataset schema.
730 
731  \param datasetName The dataset where the foreign key will be removed.
732  \param fkName The foreign key to be removed.
733 
734  \exception Exception An exception can be thrown, if the foreign key could not be removed from the dataset schema.
735 
736  \note Not thread-safe!
737  */
738  virtual void dropForeignKey(const std::string& datasetName, const std::string& fkName) = 0;
739 
740  /*!
741  \brief It gets the unique key in the dataset with the given name.
742 
743  \param datasetName The dataset name.
744  \param name The unique key name.
745 
746  \exception Exception An exception can be thrown, if the unique key could not be retrieved.
747 
748  \return The unique key with the given name in the dataset.
749 
750  \note Not thread-safe!
751  */
752  virtual std::auto_ptr<te::da::UniqueKey> getUniqueKey(const std::string& datasetName, const std::string& name) = 0;
753 
754  /*!
755  \brief It gets the unique key names of the given dataset.
756 
757  \param datasetName The dataset name.
758 
759  \exception Exception An exception can be thrown, if the unique key names could not be obtained.
760 
761  \return The unique key names of the dataset.
762 
763  \note Not thread-safe!
764  */
765  virtual std::vector<std::string> getUniqueKeyNames(const std::string& datasetName) = 0;
766 
767  /*!
768  \brief It checks if a unique key with the given name exists in the dataset.
769 
770  \param datasetName The dataset name.
771  \param name The unique key name.
772 
773  \exception Exception An exception can be thrown, if the existence of the unique key could not be determined.
774 
775  \return True, if the unique key exists in the data source; otherwise, it returns false.
776 
777  \note Not thread-safe!
778  */
779  virtual bool uniqueKeyExists(const std::string& datasetName, const std::string& name) = 0;
780 
781  /*!
782  \brief It adds a unique key constraint to the dataset.
783 
784  \param datasetName The dataset where the unique key will be added.
785  \param uk The unique key constraint.
786 
787  \exception Exception An exception can be thrown, if the unique key could not be added to the dataset schema.
788 
789  \note Don't delete the given unique key, because the schema will take the ownership of it.
790  \note Not thread-safe!
791  */
792  virtual void addUniqueKey(const std::string& datasetName, UniqueKey* uk) = 0;
793 
794  /*!
795  \brief It removes the unique key constraint from the dataset.
796 
797  \param datasetName The dataset from where the unique key will be removed.
798  \param name The unique key constraint name.
799 
800  \exception Exception An exception can be thrown, if the unique key could not be removed from the dataset schema.
801 
802  \note Not thread-safe!
803  */
804  virtual void dropUniqueKey(const std::string& datasetName, const std::string& name) = 0;
805 
806  /*!
807  \brief It gets the check constraint of the dataset with the given name.
808 
809  \param datasetName The dataset name.
810  \param name The check constraint name.
811 
812  \exception Exception An exception can be thrown, if the check constraint could not be retrieved.
813 
814  \return The check constraint with the given name.
815 
816  \note Not thread-safe!
817  */
818  virtual std::auto_ptr<te::da::CheckConstraint> getCheckConstraint(const std::string& datasetName, const std::string& name) = 0;
819 
820  /*!
821  \brief It gets the check constraint names of the given dataset.
822 
823  \param datasetName The dataset name.
824 
825  \exception Exception An exception can be thrown, if the check constraint names could not be retrieved.
826 
827  \return The check constraint names of the dataset.
828 
829  \note Not thread-safe!
830  */
831  virtual std::vector<std::string> getCheckConstraintNames(const std::string& datasetName) = 0;
832 
833  /*!
834  \brief It checks if a check-constraint with the given name exists in the data source.
835 
836  \param datasetName The dataset name.
837  \param name The check-constraint name.
838 
839  \exception Exception An exception can be thrown, if the existence of the check constraint could not be determined.
840 
841  \return True, if the check-constraint exists in the dataset; otherwise, it returns false.
842 
843  \note Not thread-safe!
844  */
845  virtual bool checkConstraintExists(const std::string& datasetName, const std::string& name) = 0;
846 
847  /*!
848  \brief It adds a check constraint to the dataset.
849 
850  \param datasetName The dataset where the constraint will be added.
851  \param cc The check constraint.
852 
853  \exception Exception An exception can be thrown, if the check constraint could not be added to the dataset schema.
854 
855  \note Don't delete the given check constraint, because the schema will take the ownership of it.
856  \note Not thread-safe!
857  */
858  virtual void addCheckConstraint(const std::string& datasetName, CheckConstraint* cc) = 0;
859 
860  /*!
861  \brief It removes the check constraint from the dataset.
862 
863  \param datasetName The dataset from where the check constraint will be removed.
864  \param name The check constraint to be removed.
865 
866  \exception Exception An exception can be thrown, if the check constraint could not be removed from the dataset schema.
867 
868  \note Not thread-safe!
869  */
870  virtual void dropCheckConstraint(const std::string& datasetName, const std::string& name) = 0;
871 
872  /*!
873  \brief It gets the index with the given name from the dataset.
874 
875  \param datasetName The dataset name.
876  \param name The index name.
877 
878  \exception Exception An exception can be thrown, if the index could not be retrieved.
879 
880  \return The index with the given name.
881 
882  \note Not thread-safe!
883  */
884  virtual std::auto_ptr<te::da::Index> getIndex(const std::string& datasetName, const std::string& name) = 0;
885 
886  /*!
887  \brief It gets the index names of the given dataset.
888 
889  \param datasetName The dataset name.
890 
891  \exception Exception An exception can be thrown, if the index names could not be retrieved.
892 
893  \return The index names of the given dataset.
894 
895  \note Not thread-safe!
896  */
897  virtual std::vector<std::string> getIndexNames(const std::string& datasetName) = 0;
898 
899  /*!
900  \brief It checks if an index with the given name exists in the dataset.
901 
902  \param datasetName The dataset name.
903  \param name The index name.
904 
905  \exception Exception An exception can be thrown, if the index existence could not be determined.
906 
907  \return True, if the index exists in the dataset; otherwise, it returns false.
908 
909  \note Not thread-safe!
910  */
911  virtual bool indexExists(const std::string& datasetName, const std::string& name) = 0;
912 
913  /*!
914  \brief It adds an index to the dataset.
915 
916  \param datasetName The dataset where the index will be added.
917  \param idx The index to be added.
918  \param options A list of optional modifiers (driver specific).
919 
920  \exception Exception An exception can be thrown, if the index could not be added to the dataset schema.
921 
922  \note Don't delete the given index, because the schema will take the ownership of it.
923  \note Not thread-safe!
924  */
925  virtual void addIndex(const std::string& datasetName, Index* idx,
926  const std::map<std::string, std::string>& options) = 0;
927 
928  /*!
929  \brief It removes the index from the dataset schema.
930 
931  \param datasetName The dataset where the index will be removed.
932  \param idxName The index to be removed.
933 
934  \exception Exception An exception can be thrown, if the index could not be removed from the dataset schema.
935 
936  \note Not thread-safe!
937  */
938  virtual void dropIndex(const std::string& datasetName, const std::string& idxName) = 0;
939 
940  /*!
941  \brief It gets the sequence with the given name in the data source.
942 
943  \param name The sequence name.
944 
945  \exception Exception An exception can be thrown, if the sequence could not be retrieved from the data source.
946 
947  \return The sequence with the given name.
948 
949  \note Not thread-safe!
950  */
951  virtual std::auto_ptr<Sequence> getSequence(const std::string& name) = 0;
952 
953  /*!
954  \brief It gets the sequence names available in the data source.
955 
956  \note Each sequence in the data source must have a unique name. For example, in a DBMS the name
957  may contain the schema name before the sequence name separated by a dot notation (".").
958 
959  \exception Exception An exception can be thrown, if the sequence names could not be retrieved.
960 
961  \return The sequence names of the data source.
962 
963  \note Not thread-safe!
964  */
965  virtual std::vector<std::string> getSequenceNames() = 0;
966 
967  /*!
968  \brief It checks if a sequence with the given name exists in the data source.
969 
970  \param name The sequence name.
971 
972  \exception Exception An exception can be thrown, if the index existence could not be determined.
973 
974  \return True, if the sequence exists in the data source; otherwise, it returns false.
975 
976  \note Not thread-safe!
977  */
978  virtual bool sequenceExists(const std::string& name) = 0;
979 
980  /*!
981  \brief It creates a new sequence in the data source.
982 
983  \exception Exception An exception can be thrown, if the sequence could not be added to the data source.
984 
985  \note Don't delete the given sequence, because the schema will take the ownership of it.
986  \note Not thread-safe!
987  */
988  virtual void addSequence(Sequence* sequence) = 0;
989 
990  /*!
991  \brief It removes the sequence from the data source.
992 
993  \param name The sequence that will be removed.
994 
995  \exception Exception An exception can be thrown, if the sequence could not be removed from the data source.
996 
997  \note Not thread-safe!
998  */
999  virtual void dropSequence(const std::string& name) = 0;
1000 
1001  /*!
1002  \brief It retrieves the bounding rectangle of the spatial property for the given dataset.
1003 
1004  \param datasetName The dataset name.
1005  \param propertyName The spatial property name.
1006 
1007  \exception Exception An exception can be thrown, if the extent of the geometry property could not be retrieved.
1008 
1009  \return The spatial property bounding rectangle, or NULL, if none can be retrieved.
1010 
1011  \note Not thread-safe!
1012  */
1013  virtual std::auto_ptr<te::gm::Envelope> getExtent(const std::string& datasetName,
1014  const std::string& propertyName) = 0;
1015 
1016  /*!
1017  \brief It retrieves the bounding rectangle for the spatial property lying in the given position in the dataset.
1018 
1019  \param datasetName The dataset name.
1020  \param propertyPos The spatial property position.
1021 
1022  \exception Exception An exception can be thrown, if the extent of the geometry property lying in the given position could not be retrieved.
1023 
1024  \return The spatial property bounding rectangle, or NULL if none can be retrieved.
1025 
1026  \note Not thread-safe!
1027  */
1028  virtual std::auto_ptr<te::gm::Envelope> getExtent(const std::string& datasetName,
1029  std::size_t propertyPos) = 0;
1030 
1031  /*!
1032  \brief It retrieves the number of items of the given dataset.
1033 
1034  \param datasetName The dataset name.
1035 
1036  \exception Exception An exception can be thrown, if the number of items of the dataset could not be retrieved.
1037 
1038  \return The number of items of the given dataset.
1039 
1040  \note Not thread-safe!
1041  */
1042  virtual std::size_t getNumberOfItems(const std::string& datasetName) = 0;
1043 
1044  /*!
1045  \brief It checks if the data source has any dataset.
1046 
1047  \exception Exception An exception can be thrown, if it is not possible to check if the data source has datasets .
1048 
1049  \return True, if the data source has datasets; otherwise, it returns false.
1050 
1051  \note Not thread-safe!
1052  */
1053  virtual bool hasDataSets() = 0;
1054 
1055  /*!
1056  \brief It checks if a dataset with the given name exists in the data source.
1057 
1058  \param name The dataset name.
1059 
1060  \exception Exception An exception can be thrown, if the existence of a dataset in the data source could not be determined.
1061 
1062  \return True, if the dataset exists in the data source; otherwise, it returns false.
1063 
1064  \note Not thread-safe!
1065  */
1066  virtual bool dataSetExists(const std::string& name) = 0;
1067 
1068  //@}
1069 
1070  /** @name Dataset Schema Persistence Methods
1071  * Methods for dealing with datasource and dataset schema changes.
1072  */
1073  //@{
1074 
1075  /*!
1076  \brief It creates the dataset schema definition in the target data source.
1077 
1078  If a dataset schema with the same name already exists in the target data source,
1079  this may throw an exception.
1080 
1081  After calling this method, the dataset schema may be updated.
1082 
1083  \param dt The dataset schema to be created. It may be changed during the operation.
1084  \param options A list of optional modifiers (driver specific).
1085 
1086  \pre The schema of a related dataset in a foreign key must be already in the data source.
1087 
1088  \post In some data sources, this method may output implicit indexes, sequences or constraints.
1089  The method, if necessary, will create and adjust the dataset schema.
1090 
1091  \post The caller of this method will take the ownership of the given schema.
1092 
1093  \note If you want to create a new schema based on an already existing one,
1094  you must create a fresh copy of the DataSetType with the clone() method.
1095 
1096  \note Not thread-safe!
1097  */
1098  virtual void createDataSet(DataSetType* dt, const std::map<std::string, std::string>& options) = 0;
1099 
1100  /*!
1101  \brief It clones the dataset in the data source.
1102 
1103  \param name The dataset to be cloned.
1104  \param cloneName The name of the cloned dataset.
1105  \param options A list of optional modifiers. It is driver specific.
1106 
1107  \exception Exception An exception can be thrown, if the dataset schema could not be cloned.
1108  \note Not thread-safe!
1109  */
1110  virtual void cloneDataSet(const std::string& name,
1111  const std::string& cloneName,
1112  const std::map<std::string, std::string>& options) = 0;
1113 
1114  /*!
1115  \brief It removes the dataset schema from the data source.
1116 
1117  \param name The dataset name whose schema will be removed from the data source.
1118 
1119  \exception Exception An exception can be thrown, if the dataset could not be removed from the data source.
1120 
1121  \note Not thread-safe!
1122  */
1123  virtual void dropDataSet(const std::string& name) = 0;
1124 
1125  /*!
1126  \brief It renames a dataset.
1127 
1128  \param name The name of the dataset to be renamed.
1129  \param newName The new dataset name.
1130 
1131  \exception Exception An exception can be thrown, if the dataset could not be renamed.
1132 
1133  \note Not thread-safe!
1134  */
1135  virtual void renameDataSet(const std::string& name, const std::string& newName) = 0;
1136  //@}
1137 
1138  /** @name Dataset Persistence Methods
1139  * Methods for dealing with the persistence of data in a data source.
1140  */
1141  //@{
1142 
1143  /*!
1144  \brief It adds data items to the dataset in the data source.
1145 
1146  \param datasetName The target dataset name.
1147  \param d The data items to be added to the dataset.
1148  \param options A list of optional modifiers (driver specific).
1149  \param limit The number of items to be used from the input dataset. If set to 0 (default), all items are used.
1150 
1151  \exception Exception An exception can be thrown, if the input dataset items could not be added to the given dataset.
1152 
1153  \note The dataset reading will start in the current position.
1154  So, keep in mind that it is the caller responsability
1155  to inform the right position(and a valid one) in the dataset 'd', to start the inserting process.
1156 
1157  \note Not thread-safe!
1158  */
1159  virtual void add(const std::string& datasetName,
1160  DataSet* d,
1161  const std::map<std::string, std::string>& options,
1162  std::size_t limit = 0) = 0;
1163 
1164  /*!
1165  \brief It removes all the informed items from the dataset.
1166 
1167  It removes all the data items from a dataset which are identified by
1168  a set of object identifiers. If this set is not informed, all items will be removed.
1169 
1170  \param datasetName The dataset name.
1171  \param oids A list of object identifiers used to remove data from the datasource, or NULL for all.
1172 
1173  \exception Exception An exception can be thrown, if the data items could not be removed.
1174 
1175  \note Not thread-safe!
1176  */
1177  virtual void remove(const std::string& datasetName, const ObjectIdSet* oids = 0) = 0;
1178 
1179  /*!
1180  \brief It updates the contents of a dataset for the set of data items.
1181 
1182  \param datasetName The target dataset name.
1183  \param dataset The list of data items to be updated.
1184  \param properties The list of properties of the dataset to be updated.
1185  \param oids The list of objects to be updated.
1186  \param options A list of optional modifiers. It is driver specific.
1187  \param limit The number of items to be used from the input dataset. If set to 0 (default) all items are used.
1188 
1189  \exception Exception An exception can be thrown, if the dataset could not be updated.
1190 
1191  \note The dataset reading will start in the
1192  current position. So, keep in mind that it is the caller responsability
1193  to inform the right position(and a valid one) for the dataset 'd', to start the updating process.
1194 
1195  \note Not thread-safe!
1196  */
1197  virtual void update(const std::string& datasetName,
1198  DataSet* dataset,
1199  const std::vector<std::size_t>& properties,
1200  const ObjectIdSet* oids,
1201  const std::map<std::string, std::string>& options,
1202  std::size_t limit = 0) = 0;
1203 
1204  /*!
1205  \brief It updates the contents of a dataset.
1206 
1207  All rows are edited. The third parameter tells wich columns are edited for each row.
1208 
1209  \param datasetName Name pf the dataset.
1210  \param dataset Dataset with editions.
1211  \param properties Columns edited for each row. Note that the size of \a properties must be the same of the \a dataset.
1212  \param ids List of positions of the columns that identifies rows.
1213 
1214  \exception te::da::Exception An exception can be thrown, if the dataset could not be updated.
1215  */
1216  virtual void update(const std::string& datasetName,
1217  DataSet* dataset,
1218  const std::vector< std::set<int> >& properties,
1219  const std::vector<size_t>& ids);
1220 
1221  /*!
1222  \brief For some data access drivers, this method will perform some operations to optimize the data storage.
1223 
1224  This is can be a typical maintenance command in database systems (like vacuum).
1225 
1226  \param opInfo Any information needed by the underlying driver in order to fine tune the optimization.
1227 
1228  \exception Exception It may throw an exception if something goes wrong.
1229 
1230  \note Not thread-safe!
1231 
1232  \note For some systems you must assure that no other thread are executing commands against the data source.
1233 
1234  \note For some drivers, this method has no effect.
1235  */
1236  virtual void optimize(const std::map<std::string, std::string>& opInfo) = 0;
1237  //@}
1238  };
1239 
1240  typedef boost::shared_ptr<DataSourceTransactor> DataSourceTransactorPtr;
1241 
1242  } // end namespace da
1243 } // end namespace te
1244 
1245 #endif // __TERRALIB_DATAACCESS_INTERNAL_DATASOURCETRANSACTOR_H
A class that models the description of a dataset.
Definition: DataSetType.h:72
boost::shared_ptr< DataSourceTransactor > DataSourceTransactorPtr
SpatialRelation
Spatial relations between geometric objects.
Definition: Enums.h:127
It describes a sequence (a number generator).
Definition: Sequence.h:56
A class that describes a check constraint.
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
AccessPolicy
Supported data access policies (can be used as bitfield).
Definition: Enums.h:40
TraverseType
A dataset can be traversed in two ways:
Definition: Enums.h:53
An Envelope defines a 2D rectangular region.
Definition: Envelope.h:51
A class that models an object that submits commands in batch to the data source.
This class represents a set of unique ids created in the same context. i.e. from the same data set...
Definition: ObjectIdSet.h:55
URI C++ Library.
It models a foreign key constraint for a DataSetType.
Definition: ForeignKey.h:50
A class that models a prepared query.
It describes a unique key (uk) constraint.
Definition: UniqueKey.h:53
A DataSourceTransactor can be viewed as a connection to the data source for reading/writing things in...
Geometry is the root class of the geometries hierarchy, it follows OGC and ISO standards.
Definition: Geometry.h:74
A Select models a query to be used when retrieving data from a DataSource.
Definition: Select.h:65
A dataset is the unit of information manipulated by the data access module of TerraLib.
Definition: DataSet.h:112
It describes a primary key (pk) constraint.
Definition: PrimaryKey.h:52
#define TEDATAACCESSEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:97
A Query is independent from the data source language/dialect.
Definition: Query.h:46
It describes an index associated to a DataSetType.
Definition: Index.h:54