MemoryPersistenceStrategy.h

Go to the documentation of this file.

#pragma once
 
#include <string>
 
#include <ArmarXCore/core/services/tasks/PeriodicTask.h>
 
#include "RobotAPI/libraries/armem/core/MemoryID.h"
#include <RobotAPI/libraries/armem/core/wm/memory_definitions.h>
#include <RobotAPI/libraries/armem/server/wm/memory_definitions.h>
 
namespace armarx::armem::server::ltm::persistence
{
  /**
   * For usage if you might want to create the key using some logic
   * defined with your strategy rather than the caller.
   *
   * NOTE: Not used currently
   */
  class ItemIdentifier {
    public:
      virtual ~ItemIdentifier();
 
      virtual std::string getKey();
  };
 
  /**
   * Retrieved items' data with an origin (resp. the strategy identifier).
   * Why an origin? Used to display which LTM sink provided the entity instance.
   */
  struct ItemResult
  {
    std::string origin;
    std::vector<unsigned char> data;
  };
 
  /**
   * @brief Abstract memory persistence strategy (resp. LTM sink)
   * 
   * Given a memory id, we can store items for it. A memory id is in terms of the persistence strategy an container that
   * again might contain other containers or items with the actual data.
   * We can also retrieve the current containers, which are a hierarchy below of the current memory id.
   * The export name specifies our specific LTM export. You might want to write different exports with the same strategy.
   * Nonetheless you could also create another strategy (@see RedundantPersistenceStrategy)
   * 
   * Why do we basically have to supply the MemoryID everywhere?
   * The first approach had an internal variable to the memory id, as it is kind of bound the memory hierarchy level and thus the id. 
   * But even though the MemoryID was stored by pass-by-value
   * there was still somewhere and somehow and sometimes a reference to it, getting you into Teufels-Küche.
   * Because the MemoryID is extended with finer hierarchy details, having the sideeffect, that this memory id would be changed.
   * Also you needed a clone function, now you can just pass the strategy pointer.
   *
   *
   *
   * How are the containers created?
   * -> Implicitly, whenever a item underneath is stored
   *
   * Want to create a new fancy ltm sink option? Maybe MongoDB?
   * -> Implement this interface and add it similar to the existing strategy (e.g. DiskPersistence) at all locations. 
   *    Don´t forget any ice proxies! (a powerful full text search is your friend)
   */
  class MemoryPersistenceStrategy {
    public:
      MemoryPersistenceStrategy() : MemoryPersistenceStrategy("Unspecified", "DefaultExport") {}
 
      /**
       * @param identifier basically a unique name for the strategy (important if you use different strategies @see RedundantPersistenceStrategy)
       * @param exportName identifier for the exported memory where any items are written (e.g. a directory)
       */
      MemoryPersistenceStrategy(const std::string& identifier, const std::string& exportName, bool enabled = true) : identifier_(identifier), exportName_(exportName), enabled_(enabled) {}
 
      virtual ~MemoryPersistenceStrategy() = default;
 
      /**
       * Returns keys that allow use to move a step further in the hierarchy (e.g. if our memory id ends in a core segment it gives us the provider segment keys).
       */
      virtual std::vector<std::string> getContainerKeys(const armarx::armem::MemoryID& id) = 0;
 
      /**
       * Keys of the actual items containing data stored for the memory id.
       */
      virtual std::vector<std::string> getItemKeys(const armarx::armem::MemoryID& id) = 0;
 
      virtual bool containsContainer(const armarx::armem::MemoryID& id, std::string key) = 0;
 
      virtual bool containsItem(const armarx::armem::MemoryID& id, std::string key) = 0;
 
      /**
       * Stores an item containing actual data for the current memory id.
       * How it is stored depends on the implementation of a concrete strategy (e.g. on disk in a specific directory).
       * 
       * @param key unique identifier of our item for the specific id (e.g. filename). 
       * Note the keys can be equal for different id levels. So you might find the same key on the core segment level as well as on the entity level.
       * @param data actual data written to the persistent item
       */
      virtual void storeItem(const armarx::armem::MemoryID& id, std::string key, std::vector<unsigned char>& data) = 0;
 
      // If you need a more powerful identification than a string as key (nonetheless the end will probably also again be a string) 
      void storeItem(const armarx::armem::MemoryID& memoryId, ItemIdentifier itemIdentifer, std::vector<unsigned char>& data)
      {
        storeItem(memoryId, itemIdentifer.getKey(), data);
      }
 
      /**
       * Retrieve the actual data of an item stored for the memory id.
       *
       * @return stored data
       */
      virtual std::vector<unsigned char> retrieveItem(const armarx::armem::MemoryID& id, std::string key) = 0;
 
      /**
       * Retrieves the actual data but also appends the origin which is in this case the strategy identifier
       */
      virtual ItemResult retrieveItemWithOrigin(const armarx::armem::MemoryID& id, std::string& key) 
      {
        ItemResult res;
        res.origin = identifier_;
        res.data = retrieveItem(id, key);
        return res;
      }
 
      std::vector<unsigned char> retrieveItem(const armarx::armem::MemoryID& memoryId, ItemIdentifier itemIdentifier)
      {
        return retrieveItem(memoryId, itemIdentifier.getKey());
      }
 
      virtual void setExportName(const std::string& exportName)
      {
        exportName_ = exportName;
      }
 
      std::string getExportName()
      {
        return exportName_;
      }
 
      std::string getIdentifier()
      {
        return identifier_;
      }
 
      void setIdentifier(const std::string& identifier)
      {
        identifier_ = identifier;
      }
 
      virtual bool isEnabled()
      {
        return enabled_;
      }
 
      virtual void disable()
      {
        enabled_ = false;
      }
 
      virtual void enable()
      {
        enabled_ = true;
      }
 
      virtual void createPropertyDefinitions(PropertyDefinitionsPtr& defs, const std::string& prefix) = 0;
 
      static const int DEPTH_TO_DATA_FILES = 7;
 
      static const constexpr char* TYPE_FILENAME = "type.aron";
      static const constexpr char* DATA_FILENAME = "data.aron";
      static const constexpr char* METADATA_FILENAME = "metadata.aron";
 
      static const constexpr char* MEMORY_EXPORT_SUFFIX = "_";
 
    protected:
      /**
       * Name of the strategy. Should be unique to avoid ambiguities.
       */
      std::string identifier_;
 
      /**
       * Name of the specific memory export where our items should be stored.
       * If you change the export name you will probably write the data to another target (e.g. different directory).
       */
      std::string exportName_;
 
      /**
       * If false, the strategy is not writing or reading anything.
       * Only default values are returned if necessary.
       */
      bool enabled_ = true;
  };
} // namespace armarx::armem::server::ltm::persistence