Service.hpp

Go to the documentation of this file.

/*
Copyright 2007, 2008, 2009, 2010, 2011 Instituto de Sistemas e Robotica, Instituto Superior Tecnico

This file is part of MeRMaID.

MeRMaID 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.

MeRMaID 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 MeRMaID.  If not, see <http://www.gnu.org/licenses/>.
*/



/**
 * @Filename Service.hpp
 * @Description Support Service declaration
 * @Status Work in Progress
 * @Version $Id: Service.hpp 1 2011-03-04 18:13:18Z jreis $
 * @Maintainer Marco Barbosa
 */


#ifndef __SUPPORT_SERVICE_H
#define __SUPPORT_SERVICE_H

namespace mermaid
{
  namespace support
  {
    namespace service
    {
      class Service;
    }
  }
}

#include <map>
#include <vector>

#include <ActiveObject.hpp>

#include <Task.hpp>
#include <XmlDocument.hpp>
#include <Logger.hpp>

#include <DataFeed.hpp>
//#include <DataFeedInputHandler.hpp>
#include <DataFeedInputHandlerMethod.hpp>
#include <ServiceConfiguration.hpp>
#include <ServiceInstanceDescription.hpp>
#include <ServiceTypeDescription.hpp>
#include <ServiceTypeDescriptionRepository.hpp>
#include <ServiceReplyHandlerMethod.hpp>
#include <ServiceRequest.hpp>
#include <ServiceRequestState.hpp>
#include <ServiceReply.hpp>
#include <ServiceInterface.hpp>
#include <ServiceInterfaceHandlerMethod.hpp>


namespace mermaid
{
  namespace support
  {
    namespace service
    {
      using mermaid::support::activeobject::ActiveObject;
      using mermaid::support::activeobject::Task;
      using boost::shared_ptr;
      using mermaid::support::xml::XmlDocument;
      using mermaid::support::logging::Logger;
      
      /**
      * @Class Service Service.hpp "Service.hpp"
      * @Description Service class.
      *
      * This is the base class of all services that will be running inside ActiveObjects.
      * @Author Marco Barbosa + Nelson Ramos
      */
      class Service
      {
          friend class ServiceReplyDeliveryTask;
          friend class ServiceDataFeedDeliveryTask;
          friend class ServiceRequestDeliveryTask;
          
        public:
          /**
          * @Description Constructor. This constructor must be called by the specific class's constructor.
          * @Author Marco Barbosa + Nelson Ramos
          */
          //Service(shared_ptr<ActiveObject> ao, shared_ptr<XmlDocument> serviceDescription, shared_ptr<ServiceTypeDescriptionRepository> serviceTypeDescriptionRepository);
          Service (shared_ptr<ActiveObject> ao, shared_ptr<Entity> entity, shared_ptr<ServiceInstanceDescription> serviceInstanceDescription, shared_ptr<ServiceConfiguration> serviceConfiguration);
          
          /**
          * @Description Destructor
          * @Author Marco Barbosa + Nelson Ramos
          */
          virtual ~Service();
          
          
          /**
          * @Description Method that is called regularly by the ServiceUpdateTask
          *
          * This method is called by the ServiceUpdateTask at a rate which is defined in the Service instance's ServiceConfiguration
          * @Author Marco Barbosa + Nelson Ramos
          */
          
          virtual void update();
          
          
          /**
           * @Description Service initializer method.
           *
           * Method that will be called when the Service is ready for user initializations.
           * @Author Marco Barbosa
           */
          virtual void initialize() = 0;
          
          //user usable stuff
          
          //request stuff
          /**
           * @Description Creates a new ServiceRequest.
           *
           * This method is used to build a new ServiceRequest to be sent to the specified target.
           * @Argument targetEntityName The name of the Entity in which the target Service is located.
           * @Argument targetServiceName The name of the target Service.
           * @Argument targetServiceInterfaceName The name of the ServiceInterface to which the ServiceRequest should be delivered.
           * @Returns A ServiceRequest configured to be sent to the specified target ServiceInterface
           * @Author Marco Barbosa
           */
          shared_ptr<ServiceRequest> makeNewServiceRequest (std::string targetEntityName, std::string targetServiceName, std::string targetServiceInterfaceName);
          
          /**
           * @Description Sends a ServiceRequest
           *
           * This method is used to send a ServiceRequest which was previously built using the makeNewServiceRequest method and to define a handler in which he corresponding ServiceReply will be handled.
           * @Argument serviceRequest The ServiceRequest to be sent (the Service to which it will be delivered was already defined in the makeNewServiceRequest method)
           * @Argument replyHandler The handler for the ServiceReply
           * @Throws ServiceRequestFailedException Throws ServiceRequestFailedException whenever it is impossible to send the Service Request.
           * @Author Marco Barbosa
           */
          void sendServiceRequest (
            shared_ptr<ServiceRequest> serviceRequest,
            shared_ptr<ServiceReplyHandlerMethodBase> replyHandlerMethod
            = shared_ptr<ServiceReplyHandlerMethodBase>());
            
          /**
           * @Description Registers a ServiceInterfaceHandler.
           *
           * This method is used to define the handler for a Service's ServiceInterface.
           * The available interfaces are defined in the ServiceTypeDescription XML file.
           * @Argument serviceInterfaceName The name of the interface for which to register the handler
           * @Argument handler The handler for this ServiceInterface
           * @Author Marco Barbosa
           */
          void registerServiceInterfaceHandlerMethod (std::string serviceInterfaceName, shared_ptr<ServiceInterfaceHandlerMethodBase> handlerMethod);
          
          /**
           * @Description Registers a DataFeedInputHandler.
           *
           * This method is used to register a DataFeedInputHandler for a specified DataFeed.
           * @Argument producerEntityName The name of the Entity in which the producer Service is located.
           * @Argument producerServiceName The name of the producer Service.
           * @Argument dataFeedName The name of the DataFeed for which this handler will handle data.
           * @Argument handlerMethod The DataFeedInputHandlerHandlerMethod which points to the handler method to be called upon reception of the data.
           * @Author Marco Barbosa
           */
          void registerDataFeedInputHandler (std::string producerEntityName, std::string producerServiceName, std::string dataFeedName, shared_ptr<DataFeedInputHandlerMethodBase> handlerMethod);
          
          /**
           * @Description Method used to send data to a DataFeed
           *
           * This method is used to send data to a DataFeed owned by the Service.
           * The available DataFeed are specified in the ServiceTypeDescription XML file.
           * @Argument dataFeedName The name of the local DataFeed to which the data is going to be sent.
           * @Argument dataBox DataBox with the data that is going to be sent to the data feed. This DataBox must have been obtained using the getDataBoxForDataFeed method.
           * @Author Marco Barbosa
           */
          void sendToDataFeed (std::string dataFeedName, shared_ptr<DataBox> dataBox);
          
          /**
           * @Description DataBox builder for a specific DataFeed.
           *
           * This method builds a DataBox formatted according to the defined data format of the specified DataFeed
           * @Argument dataFeedName The name of the DataFeed with which this DataBox should be compatible
           * @Returns A DataBox correctly formatted for the specified DataFeed..
           * @Author Marco Barbosa
           */
          shared_ptr<DataBox> getDataBoxForDataFeed (std::string dataFeedName);
          
          /**
           * @Description ServiceTypeDescription getter.
           *
           * This method returns the ServiceTypeDescription of the Service.
           * @Returns ServiceTypeDescription of the Service.
           * @Author Marco Barbosa
           */
          virtual std::vector<shared_ptr<ServiceTypeDescription> > getServiceTypeDescriptions();
          
          /**
           * @Description ServiceInstanceDescription getter.
           *
           * This method returns the ServiceInstanceDescription of the Service.
           * @Returns ServiceInstanceDescription of the Service
           * @Author Marco Barbosa
           */
          virtual shared_ptr<ServiceInstanceDescription> getServiceInstanceDescription();
          
          /**
           * @Description ServiceConfiguration getter.
           *
           * This method returns the ServiceConfiguration of the Service.
           * @Returns ServiceConfiguration of the Service
           * @Author Marco Barbosa
           */
          virtual shared_ptr<ServiceConfiguration> getServiceConfiguration();
          
          /**
           * @Description Entity getter.
           *
           * This method returns the Entity to which the Service belongs.
           * @Returns Entity to which the Service belongs.
           * @Author Marco Barbosa
           */
          virtual shared_ptr<Entity> getEntity();
          
          /**
           * @Description ActiveObject getter.
           *
           * This method returns the ActiveObject in which the Service is running.
           * @Returns ActiveObject in which the Service is running.
           * @Author Marco Barbosa
           */
          shared_ptr<ActiveObject> getActiveObject();
          
          //! @TODO Make these methods protected.
          void addServiceInterface (shared_ptr<ServiceInterface> serviceInterface);
          void addDataFeed (shared_ptr<DataFeed> dataFeed);
          
        protected:
          /**
           * @Description Service Logger getter.
           *
           * This method returns the Service Logger.
           * Use this logger for error and reporting purposes only.
           * @Returns Service Logger.
           * @Author Joao Reis
           */
          const shared_ptr<Logger>& logger() const;
          
          /**
           * @Description Quickly log a message.
           *
           * @Author Joao Reis
           */
          void logger (const std::string& msg) const;
          
          /**
           * @Description Service Debug Logger getter.
           *
           * This method returns the Service Debug Logger.
           * Use this logger for debugging purposes only.
           * @Returns Service Logger.
           * @Author Joao Reis
           */
          const shared_ptr<Logger>& debug() const;
          
          /**
           * @Description Quickly log a debug message.
           *
           * @Author Joao Reis
           */
          void debug (const std::string& msg) const;
          
        private:
          //mermaid internal stuff
          shared_ptr<ServiceInterface> getServiceInterface (std::string serviceInterfaceName);
          void processServiceRequest (shared_ptr<ServiceRequest> request);
          void processServiceReply (shared_ptr<ServiceReply> reply);
          void processDataFeedInput (std::string producerEntityName, std::string producerServiceName, std::string dataFeedName, shared_ptr<DataBox> dataBox);
          
          //data-feed stuff
          shared_ptr<DataFeed> getDataFeed (std::string dataFeedName);
          //DataFeedInputHandler getDataFeedInputHandler(std::string producerEntityName, std::string producerServiceName, std::string dataFeedName);
          shared_ptr<DataFeedInputHandlerMethodBase> getDataFeedInputHandlerMethod (std::string producerEntityName, std::string producerServiceName, std::string dataFeedName);
          
        private:
        
          // Service's used domain objects of the ServiceFramework
          shared_ptr<Entity> entity_;
          shared_ptr<ServiceInstanceDescription> serviceInstanceDescription_;
          shared_ptr<ServiceConfiguration> serviceConfiguration_;
          std::map<std::string, shared_ptr<ServiceInterface> > serviceInterfaceMap_; // maps service interface names to service interfaces
          std::map<std::string, shared_ptr<DataFeed> > dataFeedMap_;
          
          //service reply handler maps
          std::map<int, shared_ptr<ServiceReplyHandlerMethodBase> > replyHandlerMap_;
          
          //data feed handler maps
          
          // producerEntityName -> producerServiceName -> dataFeedName -> countedptr<handlerMethod>
          std::map<std::string, std::map<std::string, std::map<std::string, shared_ptr<DataFeedInputHandlerMethodBase> > > > dataFeedInputHandlerMap_;
          
          shared_ptr<ActiveObject> activeObject_;
          shared_ptr<Task> serviceUpdateTask_;
          int lastRequestId_;
          
          //service request map
          std::map<int, shared_ptr<ServiceRequest> > outgoingRequestMap_;
          void registerOutgoingServiceRequest (shared_ptr<ServiceRequest> request);
          void unregisterOutgoingServiceRequest (int requestId);
          
          static shared_ptr<ServiceTypeDescriptionRepository> serviceTypeDescriptionRepository_;
          
          // logger
          shared_ptr<Logger> logger_;
          shared_ptr<Logger> debugLogger_;
          
          // Dummy handler, used internally for requests that don't
          // need an answer
          void dummyHandler (shared_ptr<ServiceReply> reply) {}
      }; // Service
      
      inline const shared_ptr<Logger>& Service::logger() const
      {
        return logger_;
      }
      inline void Service::logger (const std::string& msg) const
      {
        logger_->step (msg);
      }
      inline const shared_ptr<Logger>& Service::debug() const
      {
        return debugLogger_;
      }
      inline void Service::debug (const std::string& msg) const
      {
        debugLogger_->step (msg);
      }
    } // namespace service
  } // namespace support
} // namespace mermaid

#endif // __SUPPORT_SERVICE_H