Task.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/process/Task.h

   \brief Abstraction that represents a Task that can be executed
 */

#ifndef __TERRALIB_PROCESS_INTERNAL_TASK_H
#define __TERRALIB_PROCESS_INTERNAL_TASK_H

 // TerraLib
#include "Config.h"

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

#include <map>
#include <memory>
#include <string>
#include <vector>

namespace te
{
  namespace process
  {
    class Connector;
    class ParameterValue;
    class TaskCapabilities;
    class TaskParameters;

    /*!
      \class Task

      \brief Abstraction that represents a Task that can be executed
    */
    class TEPROCESSEXPORT Task
    {
    public:

      enum class State
      {
        NOT_INITIALIZED, MISSING_PARAMETERS, READY_TO_RUN, RUNNING, FINISHED, FINISHED_WITH_ERRORS
      };

      /*!
        \brief It initializes the Task
      */
      Task(const std::string& taskType);

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

      //!< Gets the id of the task
      const std::string& getId() const;

      //< Sets the id of the task. Generally used only of a deserialization
      void setId(const std::string& id);

      //!< Gets the type of the task
      const std::string& getType() const;

      //!< Gets the capabilities of the task
      const TaskCapabilities* getCapabilities() const;

      //!< Gets the current execution state of the task
      State getState() const;

      //!< Gets the index-th parameter
      const te::process::ParameterValue* getParameter(std::size_t index) const;

      //!< Sets the index-th parameter. This object will optionally take the ownership of the value pointer
      void setParameter(std::size_t index, te::process::ParameterValue* value, bool takeOwnership);

      //!< Gets the task paramters
      const TaskParameters* getTaskParameters() const;

      //!< Sets the task paramters. This class will take the ownership of the given pointer
      void setTaskParameters(TaskParameters* taskParameters);

      //!< Adds a parameter connector to this class
      void addConnector(Connector* connector);

      //!< Removes a parameter connector to this class
      void removeConnector(Connector* connector);

      //!< Gets all the input connectors
      std::vector<Connector*> getInputConnectors() const;

      //!< Gets all the output connectors
      std::vector<Connector*> getOutputConnectors() const;

      //!< Checks if the task is valid, that is, if all the required input parameters have values OR connectors associated to them
      bool isValid(std::string& errorMessage) const;

      //!< Runs the task
      void run();

    protected:

      //!< Initializes the task. This function must be called by any class that extends this abstraction. The abstraction will take the ownership of the pointer
      void init(TaskCapabilities* capabilities);

      //!< Checks if all the input connectors are ready. If at least one connector is not ready, it returns FALSE.
      bool checkConnectorsAreReady();

      //!< Pushes the parameters into the output connectors
      void pushParametersToConnectors();

      //!< This function is called whenever the parameters are changed and is responsible for checking the parameters are valid. If they are, change the task state to Ready to Run
      void checkForReadyToRun();

      //!< Runs the task
      virtual void runImpl() = 0;

    protected:
      std::string m_taskType; //!< The type of the task. Used by the factory
      std::string m_id; //!< The ID of the task
      State m_state;
      std::unique_ptr<TaskCapabilities> m_capabilities;
      std::unique_ptr<TaskParameters> m_parameters;
      std::vector<Connector*> m_connectors;
    };

    //Typedef
    class TEPROCESSEXPORT TaskPtr : public std::unique_ptr<Task>
    {
    public:
      explicit TaskPtr(te::process::Task* task = nullptr);
      ~TaskPtr();
    };

    class TEPROCESSEXPORT TaskSharedPtr : public std::shared_ptr<Task>
    {
    public:
      explicit TaskSharedPtr(te::process::Task* task = nullptr);
      ~TaskSharedPtr();
    };

    /*!
      \class TaskFactory

      \brief Abstract factory used to create Tasks.
    */
    class TEPROCESSEXPORT TaskFactory : public te::common::AbstractFactory < te::process::Task, std::string >
    {
    public:

      /*!
        \brief Constructor.

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

      //!< Destructor
      virtual ~TaskFactory();

      //!< Gets all registered categories
      static std::vector<std::string> getCategories();

      //!< Gets all tasks from the give category
      static std::vector<std::string> getTasksFromCategory(const std::string& category);

    protected:

      static std::map<std::string, std::vector<std::string> > m_mapCategories;
    };

    //!< Wrapper function used to create taks. Used to avoid C++ to create multiple instances of the factory singleton on Windows
    TEPROCESSEXPORT Task* CreateTask(const std::string& taskType);

  } // end namespace process
}   // end namespace te

#endif  // __TERRALIB_PROCESS_INTERNAL_TASK_H