DataAccess.h

Go to the documentation of this file.

/*  Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.

    This file is part of the TerraLib - a Framework for building GIS enabled applications.

    TerraLib is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation, either version 3 of the License,
    or (at your option) any later version.

    TerraLib is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    GNU Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public License
    along with TerraLib. See COPYING. If not, write to
    TerraLib Team at <terralib-team@terralib.org>.
 */

/*!
\file dataaccess/utils/DataAccess.h

\brief Class used to centralize and control access to data in terralib. 
       It aims to create a high-level interface for simplifying the 
       concepts defined in the terralib DataAccess module.
*/

#ifndef __TERRALIB_DATAACCESS_INTERNAL_DATAACCESS_H
#define __TERRALIB_DATAACCESS_INTERNAL_DATAACCESS_H

#include "../Config.h"

// TerraLib
#include "../../datatype/AbstractData.h"
#include "../datasource/DataSource.h"
#include "../datasource/DataSourceTransactor.h"

// STL Includes
#include <memory>
#include <string>
#include <vector>

namespace te
{
  namespace core
  {
    class URI;
  }
}

namespace te
{
  namespace gm
  {
    class Envelope;
  }

  namespace da
  {
    class DataSet;
    class DataSetType;
    class DataSetTypeConverter;
    class Expression;
    class Literal;
    class ObjectIdSet;
    class Select;

    /*!
      \class DataAccess

      \brief Class used to centralize and control access to data in terralib.
             It aims to create a high-level interface for simplifying the
             concepts defined in the terralib DataAccess module.

    */
    class TEDATAACCESSEXPORT DataAccess : public te::dt::AbstractData
    {
      public:

        /*!
          \brief constructor.

          \param uri                The URI used to describe the datasource connection.
          \param dataSourceDriver   The data source type name (example: POSTGIS, ORACLE, SQLITE).
          \param dataSetName        The dataset name (not needed to inform if DataAccess will be used to create a new Dataset)

          \exception Exception An exception can be thrown, if the data source cannot be created or opened and dataset not found.

          \note A data source will be created without id information
        */
        DataAccess(const te::core::URI& uri, const std::string& dataSourceDriver, const std::string& dataSetName = "");

        /*! 
          \brief Constructor.

          \param dataSource         The data source pointer.
          \param dataSetName        The dataset name (not needed to inform if DataAccess will be used to create a new Dataset)
          
          \exception Exception An exception can be thrown, if the data source cannot be opened or dataset not found.

          \note This class will take the ownership of data source pointer
        */
        DataAccess(te::da::DataSourcePtr dataSource, const std::string& dataSetName = "");

        /*!
          \brief constructor.

          \param dataSource         The data source pointer.
          \param dataSetType        The dataset type

          \exception Exception An exception can be thrown, if the data source cannot be opened or dataset not found.

          \note This class will take the ownership of data source pointer, but will clone the received dataSetType
        */
        DataAccess(te::da::DataSourcePtr dataSource, const te::da::DataSetType* dataSetType);

        //!< Copy constructor
        DataAccess(const te::da::DataAccess& rhs);

        /*! \brief Default destructor. */
        virtual ~DataAccess();

        virtual te::dt::AbstractData* clone() const override;

        //!< Begins a transaction
        void beginTransaction();

        //!< Commits a transaction
        void commitTransaction();

        //!< Rollbacks the transaction
        void rollbackTransaction();

        //!< When handling with files, specially using OGR, the olnly way to ensure the data is writen tis to close dataSource. So this functions encapsulates it
        void flush();

        virtual int getTypeCode() const override;

        virtual std::string toString() const override;

        //!< Check if the the dataSet exists
        bool dataSetExists() const;

        /*!
         \brief Get data source connection info

         \return   String with data source connection info
      */
        std::string getDataSourceConnectionInfo() const;

        /*!
           \brief Get data set name

           \return   String with the new data set name
       */
        std::string getDataSetName() const;

        /*!
           \brief Get data set type

           \return   Pointer to the datasettype

           \note The caller of this method will NOT take the ownership of the given pointer
       */
        const te::da::DataSetType* getDataSetType() const;

        /*!
          \brief Set data set converter type.

          \param converter   The data set type converter pointer

          \note This class will take the ownership of converter pointer
        */
        void setConverter(te::da::DataSetTypeConverter* converter);

        /*!
           \brief Get data set type

           \return   Pointer to the datasettype

           \note The caller of this method will NOT take the ownership of the given pointer
        */
        te::da::DataSetTypeConverter* getConverter() const;

        /*!
          \brief Set data set restriction.

          \param select   The data set query pointer

          \note This class will take the ownership of query pointer
        */
        void setQuery(te::da::Select* select);

        /*!
           \brief Get query object

           \return   Pointer to the query object

           \note The caller of this method will NOT take the ownership of the given pointer
        */
        te::da::Select* getQuery() const;

        /*!
           \brief Get query object as string

           \return   String with the query restriction.
        */
        std::string getStrQuery() const;

        /*!
           \brief Get dataset using internal information (data source, query, datasetTypeConverter)

           \return   DataSet object
        */
        std::unique_ptr<te::da::DataSet> getDataSet() const;

        /*!
           \brief Get dataset using internal information (data source, query, datasetTypeConverter), using the given filter

           \return   DataSet object
        */
        std::unique_ptr<te::da::DataSet> getDataSet(const te::da::Expression* filter) const;

        /*!
           \brief Get the data source associated with this data access

           \return The data source associated with this data access
        */
        te::da::DataSourcePtr getDataSource() const;

        /*!
           \brief Get dataset using internal information (data source, datasetTypeConverter), but using query parameter 
                  for data restriction.

           \param select    Select object that defines the data filter information.

           \return   DataSet object
        */
        std::unique_ptr<te::da::DataSet> query(const te::da::Select& select);
        std::unique_ptr<te::da::DataSet> query(const std::string& query);

        /*!
           \brief Executes the given sql in the current transactor
        */
        void execute(const std::string& query);

        /*!
           \brief Function used to create a new DataSet into internal datasource. This class will NOT take the ownership of the dataSetType pointer

           \param dataSet    Pointer to a data set type to be created
        */
        void createDataSet(te::da::DataSetType* dataSetType);

        /*!
           \brief Function used to save data into internal datasource (if a converter was defined, it will be used)

           \param dataSet    Pointer to a data set to be saved

           \note DataAccess will take the ownership of dataset and erase the data at end
        */
        void saveDataSet(te::da::DataSet* dataSet, bool enableProgress = true);

        /*!
           \brief Function used to get distinct values ir order, from a specific attribute

           \param attributeName   String with attribute name

           \return  A vector with all distinct values from a attribute in order.
        */
        std::vector<std::string> getDistinctValues(const std::string& attributeName);

        /*!
          \brief It creates a Literal Expression based on a attribute type

          \param attributeName  Attribute name from data set

          \param value          Attribute value used to create the right Literal expression

          \return Valid pointer if the attribute type is supported and a null pointer in other case
        */
        te::da::Literal* getLiteral(const std::string& attributeName, const std::string& value);

        /*!
          \brief Gets the MBR of the data access

          \return The MBR of the data access
        */
        te::gm::Envelope getMBR() const;

        /*!
          \brief Gets the SRID of the data access

          \return The SRID of the data access
        */
        int getSRID() const;

        //!< The the objectId set to be used as a filter
        void setObjectIdSetFilter(const te::da::ObjectIdSet* objectIdSetFilter);

        //!< Gets the current transactor. If no transactor is defined, it creates one
        te::da::DataSourceTransactorPtr getTransactor() const;

        //!< Sets he transactor to be used
        void setTransactor(te::da::DataSourceTransactorPtr transactor);

      protected:

        te::da::DataSourcePtr                         m_dataSource;           //!< Data source.
        mutable te::da::DataSourceTransactorPtr       m_transactor;           //!< Transactor
        std::unique_ptr<te::da::DataSetType>          m_dataSetType;          //!< Data set type.
        std::unique_ptr<te::da::DataSetTypeConverter> m_dataSetTypeConverter; //!< DataSetType Converter
        std::unique_ptr<te::da::Select>               m_dataSetQuery;         //!< Filter used to load data with restriction
        std::string                                   m_dataSetName;          //!< Dataset name.
        std::unique_ptr<te::da::ObjectIdSet>          m_objectIdSetFilter;    //!< A optional filter containg an objectId set
    };

    class TEDATAACCESSEXPORT DataAccessPtr : public std::unique_ptr<te::da::DataAccess> 
    {
    public:
      DataAccessPtr(te::da::DataAccess* dataAccess = nullptr) : std::unique_ptr<te::da::DataAccess>(dataAccess) {};
    };
    class TEDATAACCESSEXPORT DataAccessSharedPtr : public std::shared_ptr<te::da::DataAccess> 
    {
    public:
      DataAccessSharedPtr(te::da::DataAccess* dataAccess = nullptr) : std::shared_ptr<te::da::DataAccess>(dataAccess) {};
    };
  }
}

#endif // __TERRALIB_DATAACCESS_INTERNAL_DATAACCESS_H