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