path: root/include/rba/RBAArbitrator.hpp

/**
 * Copyright (c) 2019 DENSO CORPORATION.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Arbitrator Logic class
 */

#ifndef RBAARBITORATOR_HPP
#define RBAARBITORATOR_HPP

#ifdef _MSC_VER
#ifdef _WINDLL
#define DLL_EXPORT __declspec(dllexport)
#else
#define DLL_EXPORT __declspec(dllimport)
#endif
#else
#define DLL_EXPORT
#endif

#include <string>
#include <list>
#include <memory>
#include "RBAModel.hpp"
#include "RBAResult.hpp"

/**
 * @namespace rba
 * @brief The namespace defined by Rule Based Arbitration Framework.
 */
namespace rba
{

// internal {
#ifdef RBA_USE_LOG
class RBALogManager;
#endif

class RBARuleObject;
class RBAExpression;
class RBAArbitratorImpl;
// }

/**
 * @class RBAArbitrator
 * An object that performs arbitration processing based on rules
 * generated from a model.<br>
 * Set the model generated using rba::RBAJsonParser in the constructor.
 */
class DLL_EXPORT RBAArbitrator
{
public:
  /**
   * @brief Arbitrator logic constractor.
   * @param newModel Processing model.
   * The model is generated by rba::RBAJsonParser.
   */
  RBAArbitrator(RBAModel* newModel);

  /**
   * @brief Arbitrator logic destractor.
   */
  RBAArbitrator(const RBAArbitrator&)=delete;
  RBAArbitrator(const RBAArbitrator&&)=delete;
  RBAArbitrator& operator=(const RBAArbitrator&)=delete;
  RBAArbitrator& operator=(const RBAArbitrator&&)=delete;
  virtual ~RBAArbitrator() noexcept;

public:

  /**
   * @brief Sets the model for arbitration
   * The model is generated by rba::RBAJsonParser.
   * @param newModel The model for arbitration
   * @details Replace the model with newModel. An arbitrator has only one model at all times.
   * Model can be generated by using rba::RBAJsonParser.
   * nullptr can not be set.
   */
  void setModel(RBAModel* newModel);

  /**
   * @brief Returns the model for arbitration
   * @return model The model for arbitration
   * @details Because the arbitrator always has a model, this API never returns nullptr.
   */
   const RBAModel* getModel() const;

  /**
   * @brief Set initial requirements of contents and scenes
   * @param contexts Context list of contents and scenes requests.
   *
   * Following is the structure of context name.\n
   * *<CONTENT_NAME>* / *<STATE_NAME>* \n\n
   * Example of context name: \n
   * TEL/Calling\n
   * TPMS/NORMAL\n
   * AutoDriveScene\n\n
   * You can omit "/ <STATE_NAME>" if content has only one state.
   * @details After arbitrator creation or calling clearArbitration(),
   * you can set initial state of contents and scenes for first arbitration.
   * This API does not execute arbitration.
   * The information of arbitration result will be empty.
   * Don't call this API after starting arbitration until calling clearArbitration().
   * @details
   * **Example**
   *
   * ```
   *    RBAJsonParser parser;
   *    rba::RBAModel* model = parser.parse(JSONFILE_PATH);
   *    rba::RBAArbitrator* arb = new rba::RBAArbitrator(model);
   *    
   *    std::list<std::string> defaultContents = {
   *      "CONTENT_A/NORMAL",
   *      "CONTENT_B/NORMAL",
   *      "CONTENT_C/NORMAL",
   *      "CONTENT_D/NORMAL",
   *    };
   *    arb->initialize(defaultContents);
   *    std::unique_ptr<RBAResult> result = arb->execute();
   * ```
   */
  void initialize(std::list<std::string>& contexts);

  /**
   * @brief Executes arbitration with one requirement\n
   * @param contextName
   * Context string of arbitration request.\n
   * Display request or sound request : "<CONTENT_NAME>/<STATE_NAME>"\n
   * If the content has only one state, the <STATE> can be omitted.\n
   * \n
   * Scene request : "<SCENE_NAME>"
   * @param require
   * true : request displaying / outputting content or scene on (default)\n
   * false : withdraw a request or scene off.
   *
   * @return The result of arbitration.
   * @details
   * Execute Arbitration with one requirement of a content or scene without properties. \n
   * The arbitration result as the return value will be generated at every arbitration and
   * will not be changed by another arbitration.
   * \n
   * Context indicates a content state or a scene.
   * If the content or scene is not defined in the model, the arbitration will not executed
   * and the state of the arbitration result will be UNKNWON_CONTENT_STATE.
   * In this case, other property values are undefined.\n
   * If the context is empty, this API just execute arbitration.
   * \n
   * **Exapmle**
   *
   * ```
   *    RBAJsonParser parser;
   *    rba::RBAModel* model = parser.parse(JSONFILE_PATH);
   *    rba::RBAArbitrator* arb = new rba::RBAArbitrator(model);
   *    std::unique_ptr<RBAResult> result = arb->execute("CONTENT_A/NORMAL", true);
   *    
   *    if(result->getStatusType() != rba::RBAResultStatusType::SUCCESS) {
   *      std::cout << "ERROR: Unknown context" << std::endl;
   *    }
   * ```
   * 
   */
  std::unique_ptr<RBAResult> execute(const std::string& contextName="",
				     bool require=true);

  /**
   * @brief Executes arbitration with multiple requirements\n
   * @param contexts List of contexts.
   * @param require
   * true : request displaying / outputting content or scene on (default)\n
   * false : withdraw a request or scene off.
   * @return The result of arbitration.
   * @details
   * \n
   * Execute Arbitration with multiple requirements of contents or scenes. \n
   * Contents and Scenes can be mixed in the list.
   * Display / Outputting request and withdraw request, scene on and scene off request can not be mixed.
   * The arbitration result as the return value will be generated at every arbitration and
   * will not be changed by another arbitration.
   * \n
   * Context indicates a content state or a scene.
   * If the content or scene is not defined in the model, the arbitration will not executed
   * and the state of the arbitration result will be UNKNWON_CONTENT_STATE.\n
   * In this case, other property values are undefined.\n
   * If the context is empty, this API just execute arbitration.
   * \n
   * Request order is the with the list. Beginning of the list will be treated as the first coming request.
   * \n
   * **Exapmle**
   *
   * ```
   *    RBAJsonParser parser;
   *    rba::RBAModel* model = parser.parse(JSONFILE_PATH);
   *    rba::RBAArbitrator* arb = new rba::RBAArbitrator(model);
   *    std::list<std::string> contents = {
   *      "CONTENT_A/NORMAL",
   *      "CONTENT_B/NORMAL",
   *      "CONTENT_C/NORMAL",
   *      "CONTENT_D/NORMAL",
   *    };
   *    std::unique_ptr<RBAResult> result = arb->execute(contents, true);
   *    
   *    if(result->getStatusType() != rba::RBAResultStatusType::SUCCESS) {
   *      std::cout << "ERROR: Unknown context" << std::endl;
   *    }
   * ```
   * 
   */
  std::unique_ptr<RBAResult> execute(std::list<std::string>& contexts,
				     bool require=true);

  /**
   * @brief Executes arbitration with a requirement of scene and scene properties.
   * @param sceneName The Scene name of arbitration reauest.\n
   * @param properties The list of pairs of property name and value.
   * @return The result of arbitration.
   * @details
   * \n
   * Sets the scene indicated by sceneName to the property specified
   * by properties, and execute arbitration processing.\n
   * If sceneName is empty, this API just execute arbitration.
   * If the required scene is not defined in the model, the arbitration will not executed
   * and the state of the arbitration result will be UNKNWON_CONTENT_STATE.\n
   * Even If there is a property not defined in the model, the arbitration will be executed.
   * \n
   * @note
   * You cannot set scene off and property at the same time, by this API.\n
   * Use setScene() to set scene off and properties,
   * and then call execute(const std::string&,bool) without specifying arguments.\n
   * Or Use setScene() to set properties,
   * and then call execute(scene name,false).\n
   * \n
   * @details
   * **Example**
   *
   * ```
   *    RBAJsonParser parser;
   *    rba::RBAModel* model = parser.parse(JSONFILE_PATH);
   *    rba::RBAArbitrator* arb = new rba::RBAArbitrator(model);
   *    std::list<std::pair<std::string, std::int32_t>> properties;
   *    properties.push_back(std::make_pair("Prop1", 10));
   *    properties.push_back(std::make_pair("Prop2", 20));
   *    std::unique_ptr<RBAResult> result = arb->execute("Scene1", properties);
   *    
   *    if(result->getStatusType() != rba::RBAResultStatusType::SUCCESS) {
   *      std::cout << "ERROR: Unknown context" << std::endl;
   *    }
   * ```
   */
  std::unique_ptr<RBAResult> execute(const std::string& sceneName,
				     std::list<std::pair<std::string,std::int32_t>>& properties);

  /**
   * @brief Replaces the result of arbitration
   * @param allocatableName area or zone name
   * @param contextName Context string of arbitration request.
   * @return The result of arbitration.
   * @details
   * \n
   * Replace allocated a content state to area or zone of the last arbitration result.\n
   * If the allocatableName or contextName is undefined, return the errror
   * code from the method getStatusType() of result.\n
   * If the contextName is non-active, activate the content request.
   * This API execute the "Request handling on lost" process and the
   * "Execution expression" process, and doesn't execute the check of
   * constraint expression process.
   * Therefore, this API can lead the result that does not satisfy the constraints\n
   * If the specified area or zone by allocatableName is hidden, mute or
   * attenuated, these statuses will be kept.
   * @deprecated Because there is a possibility that the result does not satisfy
   * the constraints, please use execute()
   * instead of this API.\n
   * \n
   * @details
   * **Example**
   *
   * ```
   *    RBAJsonParser parser;
   *    rba::RBAModel* model = parser.parse(JSONFILE_PATH);
   *    rba::RBAArbitrator* arb = new rba::RBAArbitrator(model);
   *    std::unique_ptr<RBAResult> result = arb->execute("CONTENT_A/NORMAL", true);
   *    std::unique_ptr<RBAResult> result_replaced = arb->setResultContentState("AREA_A", "CONTENT_B/NORMAL");
   *
   *    if(result_replaced->getStatusType() != rba::RBAResultStatusType::SUCCESS) {
   *      std::cout << "ERROR" << std::endl;
   *    }
   * ```
   */
  std::unique_ptr<RBAResult>
  setResultContentState(const std::string& allocatableName,
			const std::string& contextName);

  /**
   * @brief Cancel last arbitration
   * @return The result of arbitration.
   * @details
   * \n
   * Cancel last arbitration and restore internal state immediately.\n
   * This API returns the restored result but the ViewActions will be empty.\n
   * Do not execute this function more than once continuously. In that case,
   * an error occurs.\n
   * Even when executed without performing arbitration processing,
   * an error occurs.\n
   * In case of error, the status of the arbitration result is set to 
   * CANCEL_ERROR.\n
   * \n
   * @details
   * **Example**
   *
   * ```
   *    RBAJsonParser parser;
   *    rba::RBAModel* model = parser.parse(JSONFILE_PATH);
   *    rba::RBAArbitrator* arb = new rba::RBAArbitrator(model);
   *    std::unique_ptr<RBAResult> result = arb->execute("CONTENT_A/NORMAL", true);
   *    std::unique_ptr<RBAResult> result_back = arb->cancelArbitration()
   *
   *    if(result_replaced->getStatusType() != rba::RBAResultStatusType::SUCCESS) {
   *      std::cout << "ERROR" << std::endl;
   *    }
   * ```
   */
  std::unique_ptr<RBAResult> cancelArbitration();

  /**
   * @brief Clear internal states of arbitration.
   * @details
   * \n
   * Initialize internal states of arbitration (ex. Previous arbitration
   * result, request of content states, etc...) and set to the initial state.\n
   * \n
   * @note
   * This API is intended for setting up initial state of unit tests.\n
   * \n
   * @details
   * **Example**
   *
   * ```
   *    std::unique_ptr<RBAResult> result1 = arb->execute("CONTENT_A/NORMAL", true);
   *    std::unique_ptr<RBAResult> result2 = arb->execute("CONTENT_B/NORMAL", true);
   *    // reset display requests
   *    arb->clearArbitration();
   *    std::unique_ptr<RBAResult> result2 = arb->execute("CONTENT_C/NORMAL", true);
   *    std::unique_ptr<RBAResult> result3 = arb->execute("CONTENT_D/NORMAL", true);

   *
   * ```
   */
  void clearArbitration();

  /**
   * @brief Sets scene ON/OFF requests and properties.
   * @param sceneName The Scene name of arbitration reauest.\n
   * @param require true : Valid request.\n
   * false : Invalid request.
   * @param properties The pair of property name and value.\n
   * @return true: Success\n
   * @return false: Unknown scene\n
   * @details
   * \n
   * Sets the scene indicated by sceneName to the property specified
   * by properties, and without execute arbitration processing.\n
   * Returns true if the scene set succeeded. If an unknown scene name is
   * specified, false is returned.\n
   * \n
   * @note
   * This API is intended for setting up initial state of unit tests\n
   * or setting global scene and scene properties.\n
   * \n
   * @details
   * **Example**
   *
   * ```
   *    std::list<std::pair<std::string, std::int32_t>> props;
   *    props.push_back(std::make_pair("PropertyA", 10);
   *    props.push_back(std::make_pair("PropertyB", -3);
   *    res = arb->setScene("SCENE_A", true, props);
   *    if(res == false) {
   *        // Unknwon scene
   *    }
   * ```
   */
  bool setScene(const std::string& sceneName, bool require,
		std::list<std::pair<std::string, std::int32_t>>& properties);

  /**
   * @brief Sets content requests or scene ON/OFF request.
   * @param contextName Context string of arbitration request.\n
   * @param require
   * true : request displaying / outputting content or scene on (default)\n
   * false : withdraw a request or scene off.
   * @return true: Success\n
   * @return false: Unknown context\n
   * @details
   * \n
   * Sets a display request for the context without arbitration.\n
   * Returns true if the request setting is succeeded. If an unknown context
   * name is specified, false is returned.\n
   * \n
   * @note
   * This API is intended for setting up initial state of unit tests.\n
   * While initialize() has only the function to turn on the request,
   * this API can turn off the request. It is used for switch of each
   * requests when initialization setting of unit test.\n
   * \n
   * @details
   * **Example**
   *
   * ```
   *    res = arb->setContentState("ContentA/NORMAL", true);
   *    if(res == false) {
   *        // Unknwon context
   *    }
   * ```
   */
  bool setContentState(const std::string& contextName, bool require);

  /**
   * @brief Allocates content state to area or zone.
   * @param allocatableName Name of area or zone
   * @param contextName Context string of content state.\n
   *  contextName : "<CONTENT_NAME>/<STATE_NAME>"\n
   * If the content has only one state, the <STATE> can be omitted.\n
   * \n
   * @return true: Success\n
   * @return false: Unknown area, zone or context\n
   * @details
   * \n
   * Allocates the content state to the area or zone. Arbitration and
   * post arbitration will not be executed.\n
   * The display / outputting request of the specified content state will be active.
   * The statuses of hidden, mute and attenuated will not be changed.\n
   * Returns true if the request setting is succeeded. If an unknown context
   * name is specified, false is returned.\n
   *
   * @note
   * This API is intended for setting up initial state of unit tests.\n
   * In setResultContentState(), in addition to content state assignment,
   * evaluation of the action determination process at the time of arbitration
   * losing and control execution expression is performed, whereas in this
   * API only content state assignment is performed.\n
   * \n
   * @deprecated
   * Since there is a possibility of contradiction with the
   * constraint, it is recommended not to use it except unit test.
   * \n
   * @details
   * **Example**
   *
   * ```
   *    res = arb->setAllocatableResult("AreaA", "ContentA/NORMAL");
   *    if(res == false) {
   *        // Unknwon area, zone or context
   *    }
   * ```
   */
  bool setAllocatableResult(const std::string& allocatableName,
			    const std::string& contextName);
  // internal {
#ifdef RBA_USE_LOG
  RBAArbitrator(RBAModel* newModel, RBALogManager* logManager);
#endif
  bool evaluate(RBAExpression* expression);
  const RBARuleObject* evaluateObject(RBAExpression* expression);
  int32_t evaluateValue(RBAExpression* expression);

  RBAArbitratorImpl* getImpl() const;
  // }

private:
  class Impl;
#ifdef _MSC_VER
#pragma warning(push)
#pragma warning(disable:4251)
#endif
  std::unique_ptr<Impl> impl_;
#ifdef _MSC_VER
#pragma warning(pop)
#endif
};

}

#endif