AbstractOperation.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 terralib/vp/AbstractOperation.h

\brief Abstract Class to represent an abstract vector operation.
*/

#ifndef __TERRALIB_VP_INTERNAL_ABSCTRACTOPERATION_H
#define __TERRALIB_VP_INTERNAL_ABSCTRACTOPERATION_H

#include "Config.h"

#include "../common/AbstractFactory.h"
#include "../geometry/Enums.h"

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

namespace te
{
  namespace da
  {
    class DataAccess;
    class DataSetType;
  }

  namespace vp
  {
    struct AbstractOperationImpl;
    class Feature;
    class FeatureSet;
    class OperationReport;

    enum class OperationResult
    {
      OP_NOT_STARTED, OP_SUCCESS, OP_CANCELLED, OP_ERROR
    };

    /*!
      \class AbstractParameters

      \brief Abstract class used to define the input/ ouptut parameters for TerraAmazon Operations.

      \note Not all parameters must be defined, each operation will validate the necessary parameters.
    */
    class TEVPEXPORT AbstractParameters
    {
    public:

      /*! \brief Default constructor. */
      AbstractParameters();

      /*! \brief Virtual destructor. */
      virtual ~AbstractParameters() = default;

    public:

      /*!
        \brief It checks the parameters for the operation.

        \return True if the parameters is valid for this operation and false in other cases.
      */
      virtual bool isValid(std::string& errorMessage);

      /*!
        \brief It reports each parameter used in the operation

        \param  report  Object used to report operation information.
      */
      void reportParams(OperationReport* report);

      /*!
        \brief Adds an input data access to the params

        \param dataAccess The input dataAccess to be added
      */
      void addInputDataAccess(te::da::DataAccess* dataAccess);

      /*!
        \brief Adds an output data access to the params. Note that if the dataSet does not exist, it will be created by the operation

        \param dataAccess The output dataAccess to be added
      */
      void addOutputDataAccess(te::da::DataAccess* dataAccess);

      //!< Returns the input dataAccess vector
      const std::vector<te::da::DataAccess*>& getInputDataAccessVector() const;

      //!< Returns the output dataAccess vector
      const std::vector<te::da::DataAccess*>& getOutputDataAccessVector() const;

      //!< Sets the input dataAccess vector
      void setInputDataAccessVector(const std::vector<te::da::DataAccess*>& vecDataAccess);

      //!< Sets the output dataAccess vector
      void setOutputDataAccessVector(const std::vector<te::da::DataAccess*>& vecDataAccess);

      //!< Enables or disables geometry subdivision
      void setMaxCoordinates(std::size_t maxCoordinates);

      //!< Returns the current state of the geometry subdivision
      std::size_t getMaxCoordinates() const;

      //!< Sets the input to be swapped. This is very usefull for operations between 2 dataSets. If TRUE, the input will be swapped. Default is FALSE
      void setSwapInput(bool swap);

      //!< Returns TRUE if the input must be swaped. FALSE otherwise.
      bool getSwapInput() const;

      //!< Gets the result of the operation
      OperationResult getOperationResult() const;

      //!< Sets the result of the operation
      void setOperationResult(OperationResult result);

    protected:

      /*!
        \brief It reports each specific parameter used in the operation

        \param  report  Object used to report operation information.
      */
      virtual void reportSpecificParams(OperationReport* report);

    protected:

      std::vector<te::da::DataAccess*> m_inputDataVector; //!< Vector with input dataAccess
      std::vector<te::da::DataAccess*> m_outputDataVector; //!< Vector with output dataAccess
      bool                             m_swapInput; //!< This is very usefull for operations between 2 dataSets. If TRUE, the input will be swapped. Default is FALSE
      bool                             m_snapGeometries; //!< If TRUE, the geometries will be snapped before the operation is executed. Default is TRUE
      OperationResult                  m_operationResult; //!< Stores the result of the operation
      std::size_t                      m_maxCoordinates; //!< If higher than 0, geometries will be subdivided until all the parts have less vertexes that this value
    };

    /*!
      \class AbstractOperationCapabilities

      \brief Abstract class used to define the capabilities of the operation, inclusing number of inputs and outputs.
    */
    class TEVPEXPORT AbstractOperationCapabilities
    {
    public:
      AbstractOperationCapabilities(const std::string& operationName, std::size_t numberOfInputs, std::size_t numberOfOutputs, const std::string& dataHandlerName, bool snapGeometries, bool allowCoordinateSubdivision);

      //!< Destructor
      virtual ~AbstractOperationCapabilities();

      //!< Returns the number of inputs of the operation
      std::size_t getNumberOfInputs() const;

      //!< Returns the number of outputs of the operation
      std::size_t getNumberOfOutputs() const;

      //!< Returns the name of the operation
      const std::string& getName() const;

      //!< Returns TRUE if the operation supports the subdivision of the geometries. FALSE otherwise
      const std::string& getDataHandlerName() const;

      //!< Checks if the geometries must be snapped to each other before the operation is executed
      bool getSnapGeometries() const;

      //!< Checks if the operation has the capability to handle geometry coordinate subdivision
      bool getAllowCoordinateSubdivision() const;

      //!< Creates the parameters for this operation. If the concrete operation has specific parameters, it must override this class and instantiate the correct parameters
      virtual std::unique_ptr<AbstractParameters> createParameters() const;

    protected:

      std::string m_operationName; //!< The name of the operation
      std::size_t m_numberOfInputs; //!< The number of inputs of the operation
      std::size_t m_numberOfOutputs; //!< The number of outputs of the operation
      std::string m_dataHandlerName; //!< TRUE if the operation supports the subdivision of the geometries. FALSE otherwise
      bool m_snapGeometries; //!< TRUE if the geometries must be snapped to each other before the operation is executed.  FALSE otherwise. Default is TRUE
      bool m_allowCoordinateSubdivision; //!< TRUE if the operation has the capability to handle geometry coordinate subdivision
    };

    /*!
      \class AbstractOperation

      \brief Abstract class used to define an operation.
    */
    class TEVPEXPORT AbstractOperation
    {
    public:

      /*!
        \brief Default constructor.

        \note This class will take the ownership of AbstractParameters pointer
      */
      AbstractOperation(const std::string& operationName);

      /*! \brief Virtual destructor. */
      virtual ~AbstractOperation();

      //!< Initializes the operation input and output
      virtual void initialize();

      /*!
        \brief It executes the operation.

        \param input Input vector data to be processed.

        \pre The parameters must be valid (internal check)

        \exception Exception It throws an exception if something goes wrong during the execution.

        \Return The output memory data processed.
      */
      virtual std::vector<te::vp::FeatureSet> execute(const std::vector<te::vp::FeatureSet>& vecInput);

      /*!
        \brief It creates the output feature based on the given output dataaccess index

        \param outputIndex The index of the output dataAccess.
      */
      virtual te::vp::Feature* createOutputFeature(std::size_t outputIndex);

      /*!
        \brief Gets the dataSetType of the 'outputIndex-th' output

        \param outputIndex The index of the output dataAccess.
      */
      virtual const te::da::DataSetType* getDataSetType(std::size_t outputIndex);

      //!< Sets the parameters to be used by the operation
      void setParameters(AbstractParameters* params);

      //!< Gets the operation current parameters
      AbstractParameters* getParameters() const;

      //!< Gets the operation report
      OperationReport* getReport() const;

      //!< Gets the operation name
      const std::string& getName() const;

      //!< Gets the output geometry type
      te::gm::GeomType getOutputGeometryType() const;

      //!< Aborts the execution of the operation
      void abort();

      //!< Returns TRUE if the operation has been aborted. FALSE otherwise
      bool isAborted() const;

      //!< Get the capabilities of the operation. Basically, operation will have 2 inputs, 1 output, and support subdivision. If it is not the case of the concrete class, this function should be overriden
      virtual std::unique_ptr<te::vp::AbstractOperationCapabilities> getCapabilities() const;

      //!< Makes all the necessaries adaptations to the input dataAccess to avoid duplicate column names
      bool prepareInputData();

      bool prepareOutputData();

      bool handleOutputPropertyNamesChanges(const te::da::DataSetType* baseOutputDataSetType, const te::da::DataSetType* actualOutputDataSetType);

    protected:

      //!< Creates the basic dataSetType for the output containing all the columns that are required
      virtual te::da::DataSetType* createBasicOutputDataSetType(const std::string& dataSetName, int srid, te::gm::GeomType geometryType, const std::string& geometryColumnName) const;

      virtual void addOutputColumns(te::da::DataSetType* outputDataSetType);

      //!< Initializes the operation input
      virtual bool initializeInput();

      //!< Initializes the operation output
      virtual bool initializeOutput();

      //!< Function that effectivelly executes the operation. It must be implemented by the concrete classes
      virtual std::vector<te::vp::FeatureSet> executeImpl(const std::vector<te::vp::FeatureSet>& vecInput) = 0;

    protected:

      AbstractOperationImpl* m_impl; //!< Holds all the attributes of the class
      bool m_aborted; //!< Becames true if the abort function is called. Concrete classes must check for this value from time to time
    };

    /*!
      \class OperationFactory

      \brief Abstract factory used to create Operations.
    */
    class TEVPEXPORT OperationFactory : public te::common::AbstractFactory < te::vp::AbstractOperation, std::string >
    {
    protected:

      /*!
        \brief Constructor.

        \param factoryKey The key that identifies the factory.
      */
      OperationFactory(const std::string& factoryKey);

      //!< Destructor
      virtual ~OperationFactory();
    };

  }
}

#endif // __TERRALIB_VP_INTERNAL_ABSCTRACTOPERATION_H