KnowledgeBase.h

Go to the documentation of this file.

#ifndef _MADARA_KNOWLEDGE_BASE_H
#define _MADARA_KNOWLEDGE_BASE_H

#include <ostream>
#include <string>
#include <map>
#include <memory>

#include "madara/knowledge/KnowledgeRecord.h"
#include "madara/knowledge/KnowledgeUpdateSettings.h"
#include "madara/knowledge/Functions.h"
#include "madara/filters/Arguments.h"
#include "madara/MadaraExport.h"
#include "madara/knowledge/ThreadSafeContext.h"
#include "madara/transport/Transport.h"
#include "madara/expression/Interpreter.h"
#include "madara/utility/Refcounter.h"
#include "madara/knowledge/KnowledgeBaseImpl.h"
#include "madara/knowledge/CompiledExpression.h"
#include "madara/knowledge/VariableReference.h"


#ifdef _MADARA_PYTHON_CALLBACKS_
#include "madara/Boost.h"
#include "boost/python/object.hpp"
#endif

namespace madara
{

  namespace knowledge
  {

    class MADARA_EXPORT KnowledgeBase
    {
    public:
      KnowledgeBase ();

      KnowledgeBase (const std::string & host, int transport);

      KnowledgeBase (const std::string & host, int transport,
        const std::string & domain);

      KnowledgeBase (const std::string & host,
        const madara::transport::TransportSettings & config);

      KnowledgeBase (const KnowledgeBase & original) = default;

      void use (ThreadSafeContext & original);

      ~KnowledgeBase () = default;

      void copy (const KnowledgeBase & source,
        const KnowledgeRequirements & settings);

      void copy (const KnowledgeBase & source,
        const CopySet & copy_set = CopySet (),
        bool clean_copy = false);

      KnowledgeBase &operator= (const KnowledgeBase & original) = default;

      void activate_transport (void);

      void close_transport (void);

      size_t get_num_transports (void);

      void lock (void);

      void unlock (void);

      madara::knowledge::KnowledgeRecord get (const std::string & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings (false));

      madara::knowledge::KnowledgeRecord
        get (const VariableReference & variable,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings (false));

      VariableReference
        get_ref (const std::string & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings (false));

      std::shared_ptr<std::string> share_string(const std::string & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ()) const
      {
        if (impl_)
        {
          return impl_->share_string (key, settings);
        }
        else if (context_)
        {
          return context_->share_string (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::string> share_string(const VariableReference & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ()) const
      {
        if (impl_)
        {
          return impl_->share_string (key, settings);
        }
        else if (context_)
        {
          return context_->share_string (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::string> take_string(const std::string & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ())
      {
        if (impl_)
        {
          return impl_->take_string (key, settings);
        }
        else if (context_)
        {
          return context_->take_string (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::string> take_string(const VariableReference & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ())
      {
        if (impl_)
        {
          return impl_->take_string (key, settings);
        }
        else if (context_)
        {
          return context_->take_string (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::vector<KnowledgeRecord::Integer>>
        share_integers(const std::string & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ()) const
      {
        if (impl_)
        {
          return impl_->share_integers (key, settings);
        }
        else if (context_)
        {
          return context_->share_integers (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::vector<KnowledgeRecord::Integer>>
        share_integers(const VariableReference & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ()) const
      {
        if (impl_)
        {
          return impl_->share_integers (key, settings);
        }
        else if (context_)
        {
          return context_->share_integers (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::vector<KnowledgeRecord::Integer>>
        take_integers(const std::string & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ())
      {
        if (impl_)
        {
          return impl_->take_integers (key, settings);
        }
        else if (context_)
        {
          return context_->take_integers (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::vector<KnowledgeRecord::Integer>>
        take_integers(const VariableReference & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ())
      {
        if (impl_)
        {
          return impl_->take_integers (key, settings);
        }
        else if (context_)
        {
          return context_->take_integers (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::vector<double>>
        share_doubles(const std::string & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ()) const
      {
        if (impl_)
        {
          return impl_->share_doubles (key, settings);
        }
        else if (context_)
        {
          return context_->share_doubles (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::vector<double>>
        share_doubles(const VariableReference & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ()) const
      {
        if (impl_)
        {
          return impl_->share_doubles (key, settings);
        }
        else if (context_)
        {
          return context_->share_doubles (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::vector<double>>
        take_doubles(const std::string & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ())
      {
        if (impl_)
        {
          return impl_->take_doubles (key, settings);
        }
        else if (context_)
        {
          return context_->take_doubles (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::vector<double>>
        take_doubles(const VariableReference & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ())
      {
        if (impl_)
        {
          return impl_->take_doubles (key, settings);
        }
        else if (context_)
        {
          return context_->take_doubles (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::vector<unsigned char>>
        share_binary(const std::string & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ()) const
      {
        if (impl_)
        {
          return impl_->share_binary (key, settings);
        }
        else if (context_)
        {
          return context_->share_binary (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::vector<unsigned char>>
        share_binary(const VariableReference & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ()) const
      {
        if (impl_)
        {
          return impl_->share_binary (key, settings);
        }
        else if (context_)
        {
          return context_->share_binary (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::vector<unsigned char>>
        take_binary(const std::string & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ())
      {
        if (impl_)
        {
          return impl_->take_binary (key, settings);
        }
        else if (context_)
        {
          return context_->take_binary (key, settings);
        }

        return nullptr;
      }

      std::shared_ptr<std::vector<unsigned char>>
        take_binary(const VariableReference & key,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings ())
      {
        if (impl_)
        {
          return impl_->take_binary (key, settings);
        }
        else if (context_)
        {
          return context_->take_binary (key, settings);
        }

        return nullptr;
      }
      void mark_modified (const VariableReference & variable,
          const KnowledgeUpdateSettings & settings = KnowledgeUpdateSettings());

      void mark_modified (const std::string & name,
          const KnowledgeUpdateSettings & settings = KnowledgeUpdateSettings());

      madara::knowledge::KnowledgeRecord retrieve_index (const std::string & key,
             size_t index,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings (false));

      int read_file (const std::string & knowledge_key,
                     const std::string & filename,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int
      read_file (
        const VariableReference & variable,
        const std::string & filename,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const VariableReference & variable,
        const std::string & value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const VariableReference & variable,
        std::string && value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const VariableReference & variable,
        const KnowledgeRecord & value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const VariableReference & variable,
        KnowledgeRecord && value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const std::string & key,
        const KnowledgeRecord & value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const std::string & key,
        KnowledgeRecord && value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const VariableReference & variable,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false)) {
        return set (variable, 1, settings);
      }

      int set (const VariableReference & variable,
        const std::vector <double> & value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const VariableReference & variable,
        std::vector <double> && value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const VariableReference & variable,
        const double * value,
        uint32_t size,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      template<typename T>
      int set_index (const VariableReference & variable,
        size_t index, T&& value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      template<typename T,
        typename std::enable_if<std::is_floating_point<T>::value,
        void*>::type = nullptr>
      int set (const VariableReference & variable,
        T value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const VariableReference & variable,
        const std::vector <KnowledgeRecord::Integer> & value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const VariableReference & variable,
        std::vector <KnowledgeRecord::Integer> && value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const VariableReference & variable,
        const madara::knowledge::KnowledgeRecord::Integer * value,
        uint32_t size,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      template<typename T,
        typename std::enable_if<std::is_integral<T>::value,
        void*>::type = nullptr>
      int set (const VariableReference & variable,
        T value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set_text (const VariableReference & variable,
        const char * value, size_t size,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set_file (const std::string & key,
        const unsigned char * value, size_t size,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set_jpeg (const std::string & key,
        const unsigned char * value, size_t size,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set_file (const VariableReference & variable,
        const unsigned char * value, size_t size,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set_jpeg (const VariableReference & variable,
        const unsigned char * value, size_t size,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set_xml (const VariableReference & variable,
        const char * value, size_t size,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      madara::knowledge::KnowledgeRecord retrieve_index (
             const VariableReference & variable,
             size_t index,
             const KnowledgeReferenceSettings & settings =
          EvalSettings (false, false, true, false, false));

      ssize_t write_file (const std::string & knowledge_key,
                      const std::string & filename);

      std::string expand_statement (const std::string & statement);

      std::string debug_modifieds (void) const;

#ifndef _MADARA_NO_KARL_

      CompiledExpression
        compile (const std::string & expression);

      madara::knowledge::KnowledgeRecord evaluate (
        const std::string & expression,
        const EvalSettings & settings =
          EvalSettings ());

      madara::knowledge::KnowledgeRecord evaluate (
        CompiledExpression & expression,
        const EvalSettings & settings =
          EvalSettings ());

      madara::knowledge::KnowledgeRecord evaluate (
        expression::ComponentNode * root,
        const EvalSettings & settings =
          EvalSettings ());

      madara::knowledge::KnowledgeRecord wait (
        const std::string & expression,
        const WaitSettings & settings =
          WaitSettings ());

      madara::knowledge::KnowledgeRecord wait (
        CompiledExpression & expression,
        const WaitSettings & settings =
          WaitSettings ());

      void define_function (const std::string & name,
        knowledge::KnowledgeRecord (*func) (FunctionArguments &, Variables &));

      void define_function (const std::string & name,
        knowledge::KnowledgeRecord (*func) (const char *, FunctionArguments &, Variables &));

#ifdef _MADARA_JAVA_

      void define_function (const std::string & name, jobject callable);
#endif

#ifdef _MADARA_PYTHON_CALLBACKS_

      void define_function (const std::string & name, boost::python::object callable);
#endif

      void define_function (const std::string & name,
        const std::string & expression);

      void define_function (const std::string & name,
        const CompiledExpression & expression);

#endif // _MADARA_NO_KARL_

      template<typename T,
        typename std::enable_if<std::is_integral<T>::value,
        void*>::type = nullptr>
      int set (const std::string & key,
        T value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      template<typename T>
      int set_index (const std::string & key,
        size_t index, T&& value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const std::string & key,
        const madara::knowledge::KnowledgeRecord::Integer * value,
        uint32_t size,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const std::string & key,
        const std::vector <KnowledgeRecord::Integer> & value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const std::string & key,
        std::vector <KnowledgeRecord::Integer> && value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const std::string & key,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false)) {
        return set (key, 1, settings);
      }

      template<typename T,
        typename std::enable_if<std::is_floating_point<T>::value,
        void*>::type = nullptr>
      int set (const std::string & key, T value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const std::string & key,
        const double * value,
        uint32_t size,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const std::string & key,
        const std::vector <double> & value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const std::string & key,
        std::vector <double> && value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const std::string & key, const std::string & value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      int set (const std::string & key, std::string && value,
        const EvalSettings & settings =
          EvalSettings (false, false, true, false, false));

      void set_quality (const std::string & key, uint32_t quality,
             const KnowledgeReferenceSettings & settings =
                     KnowledgeReferenceSettings (false));

      std::string setup_unique_hostport (const std::string & host = "");

      madara::transport::TransportSettings & transport_settings (void);

      bool exists (const std::string & key,
        const KnowledgeReferenceSettings & settings =
          KnowledgeReferenceSettings (false)) const;

      bool exists (const VariableReference & variable,
        const KnowledgeReferenceSettings & settings =
          KnowledgeReferenceSettings (false)) const;

      int apply_modified (const EvalSettings & settings =
          EvalSettings ());

      int modify (const EvalSettings & settings =
        EvalSettings ());

      void print (unsigned int level = 0) const;

      void print_knowledge (unsigned int level = 0) const;

      void print (const std::string & statement,
        unsigned int level = 0) const;

      void to_string (std::string & target,
        const std::string & array_delimiter = ",",
        const std::string & record_delimiter = ";\n",
        const std::string & key_val_delimiter = "=") const;

      bool clear (const std::string & key,
        const KnowledgeReferenceSettings & settings =
        KnowledgeReferenceSettings ());

      void clear (bool erase = false);

      void reset_checkpoint (void) const;

      void clear_map (void);

      void acquire (void);

      void release (void);

      size_t attach_transport (madara::transport::Base * transport);

      size_t attach_transport (const std::string & id,
        transport::TransportSettings & settings);

      size_t remove_transport (size_t index);

      ThreadSafeContext & get_context (void);

      int get_log_level (void);

      void attach_logger (logger::Logger & logger) const;

      logger::Logger & get_logger (void) const;

      void set_log_level (int level);

      std::string get_id (void);

      void get_matches (
        const std::string & prefix,
        const std::string & suffix,
        VariableReferences & matches);

      size_t to_vector (const std::string & subject,
                              unsigned int start,
                              unsigned int end,
                              std::vector <KnowledgeRecord> & target);

      size_t to_map    (const std::string & subject,
                       std::map <std::string, knowledge::KnowledgeRecord> & target);

      size_t  to_map (const std::string & prefix,
        const std::string & delimiter,
        const std::string & suffix,
        std::vector <std::string> & next_keys,
        std::map <std::string, knowledge::KnowledgeRecord> & result,
        bool just_keys = false);

      knowledge::KnowledgeMap to_map (const std::string & prefix) const;

      knowledge::KnowledgeMap to_map_stripped (const std::string &prefix) const;

      int64_t save_context (const std::string & filename) const;

      int64_t save_context (CheckpointSettings & settings) const;

      int64_t save_as_json (const std::string & filename) const;

      int64_t save_as_json (const CheckpointSettings & settings) const;

      int64_t save_as_karl (const std::string & filename) const;

      int64_t save_as_karl (const CheckpointSettings & settings) const;

      int64_t save_checkpoint (const std::string & filename,
        bool reset_modifieds = true);

      int64_t save_checkpoint (
        CheckpointSettings & settings) const;

      int64_t load_context (const std::string & filename,
        bool use_id = true,
        const KnowledgeUpdateSettings & settings =
              KnowledgeUpdateSettings (true, true, true, false));

      int64_t load_context (const std::string & filename,
        FileHeader & meta,
        bool use_id = true,
        const KnowledgeUpdateSettings & settings =
        KnowledgeUpdateSettings (true, true, true, false));

      int64_t load_context (CheckpointSettings & checkpoint_settings,
        const KnowledgeUpdateSettings & update_settings =
        KnowledgeUpdateSettings (true, true, true, false));

      void add_modifieds (const VariableReferences & modifieds) const;

      VariableReferences save_modifieds (void) const;

      int send_modifieds (
        const std::string & prefix = "KnowledgeBase::send_modifieds",
        const EvalSettings & settings =
          EvalSettings ());

      void clear_modifieds (void);


      void wait_for_change (void);

      void facade_for (ThreadSafeContext & target);

    private:

      std::shared_ptr <KnowledgeBaseImpl> impl_;

      ThreadSafeContext * context_;
    };

  }
}

// include the inline functions
#include "KnowledgeBase.inl"

#endif   // _MADARA_KNOWLEDGE_BASE_H