caosdb/entity.h

Anything entity-related.

File descriptors are used to represent directories, links and files of the caosdb file system and their meta data.

Author: Timm Fitchen
Date: 2021-07-07
Author: Timm Fitchen
Date: 2022-01-21

namespace caosdb

namespace entity

DataTypes have 2 dimensions: They may be atomic or reference typed, and they may be scalar or list valued. If they are atomic, they have an AtomicDataType. If they are reference typed, the reference name can be obtained with GetName().

MessageCodes for entity messages.

In contrast to the status codes, the message codes are part of the CaosDB API. Messages (and their codes) represent the state of the entities in a transaction or the server.

For a specification of the message codes, look at the protobuf documentation. The sources and documentation can be found at https://gitlab.indiscale.com/caosdb/src/caosdb-proto.

Typedefs

using ProtoParent = caosdb::entity::v1::Parent

using ProtoProperty = caosdb::entity::v1::Property

using ProtoEntity = caosdb::entity::v1::Entity

using ProtoMessage = caosdb::entity::v1::Message

typedef caosdb::entity::v1::Value ProtoValue

using ProtoImportance = caosdb::entity::v1::Importance

Enums

enum Importance

The property importance.

Values:

enumerator UNSPECIFIED: Unset/None.

enumerator OBLIGATORY: Obligatory importance.

enumerator RECOMMENDED: Recommended importance.

enumerator SUGGESTED: Suggested importance.

enumerator FIX: Fix importance.

enum Role

The entity role.

Values:

enumerator UNSPECIFIED: Unset/None.

enumerator RECORD_TYPE: RecordType.

enumerator RECORD: Record.

enumerator PROPERTY: Property.

enumerator FILE: File.

Variables

static const std::string logger_name = "caosdb::entity"

const std::map<Importance, std::string> importance_names = {{Importance::UNSPECIFIED, "UNSPECIFIED"}, {Importance::OBLIGATORY, "OBLIGATORY"}, {Importance::RECOMMENDED, "RECOMMENDED"}, {Importance::SUGGESTED, "SUGGESTED"}, {Importance::FIX, "FIX"}}

const std::map<Role, std::string> role_names = {{Role::UNSPECIFIED, "UNSPECIFIED"}, {Role::RECORD_TYPE, "RECORD_TYPE"}, {Role::RECORD, "RECORD"}, {Role::PROPERTY, "PROPERTY"}, {Role::FILE, "FILE"}}

template<typename T, typename P> class RepeatedPtrFieldWrapper : public caosdb::utility::ProtoMessageWrapper<RepeatedPtrField<P>>

#include <entity.h>

Abstract base class for Messages, Properties and Parents container classes.

This is a list-like class.

This class wraps a RepeatedPtrField.

Public Functions

inline auto size() const -> int: Return the current size of the container.

inline auto at(int index) const -> const T&: Return a const reference to the element at the given index.

inline auto mutable_at(int index) const -> T*: Return a mutable pointer to the element at the given index.

auto begin() -> iterator : Return iterator positioned at the beginning of the list.

auto end() -> iterator : Return iterator positioned at the end of the list.

auto begin() const -> const iterator : Return constant iterator positioned at the beginning of the list.

auto end() const -> const iterator : Return constant iterator positioned at the end of the list.

inline virtual ~RepeatedPtrFieldWrapper()

inline virtual auto ToString() const noexcept -> const std::string override: Return a json representation of this object.

inline auto operator==(const RepeatedPtrFieldWrapper<T, P> &other) const noexcept -> bool: Return true if the underlying Protobuf messages have the same serialization.

inline auto operator!=(const RepeatedPtrFieldWrapper<T, P> &other) const noexcept -> bool: Return true if the underlying Protobuf messages have a different serialization.

Protected Functions

inline RepeatedPtrFieldWrapper()

inline explicit RepeatedPtrFieldWrapper(RepeatedPtrField<P> *wrapped)

inline auto Append(const T &element) -> void: Append an element. This adds the element to the end of the wrapped list and increases the size by one.

inline auto Remove(int index) -> void: Remove the element at the given index.

inline auto Clear() noexcept -> void

Protected Attributes

mutable std::map<int, T> cache

Friends

friend class Entity

class iterator : public std::iterator<std::output_iterator_tag, T>

Public Functions

explicit iterator(const RepeatedPtrFieldWrapper<T, P> *instance, int index = 0)

auto operator*() const -> T&

auto operator++() -> iterator&

auto operator++(int) -> iterator 

auto operator!=(const iterator &rhs) const -> bool

Private Members

int current_index = 0

const RepeatedPtrFieldWrapper<T, P> *instance

class Message : public caosdb::utility::ScalarProtoMessageWrapper<ProtoMessage>

#include <entity.h>

Messages convey information about the state of entities and result of transactions.

A Message object can be thought of as kinf of a generalized error object in other frameworks. Please have a look at MessageCodes for more details.

Public Functions

inline auto GetCode() const -> MessageCode 

Get the code of this message.

The message code is a unique identifier of the type of message and is intended to make it easiert to identify messages in a machine-readable way.

inline auto GetDescription() const -> std::string

Get the description of this message.

The description is intended for a human reader.

Private Functions

inline explicit Message(ProtoMessage *wrapped)

Friends

friend class Entity

friend class Messages

friend class RepeatedPtrFieldWrapper< Message, ProtoMessage >

class Messages : public caosdb::entity::RepeatedPtrFieldWrapper<Message, ProtoMessage>

#include <entity.h>

Container for Messages.

Private Functions

inline Messages()

Friends

friend class Entity

class Parent : public caosdb::utility::ScalarProtoMessageWrapper<ProtoParent>

#include <entity.h>

Parent of an Entity.

This implementation uses protobuf messages as storage backends. In other words, this class wraps a protobuf message and provides getter and setter methods.

Public Functions

inline explicit Parent(ProtoParent *wrapped)

inline Parent()

~Parent() = default

inline Parent(const Parent &other): Copy constructor.

inline Parent(Parent &&other): Move constructor.

inline auto operator=(const Parent &other) -> Parent&: Copy assignment operator.

inline auto operator=(Parent &&other) -> Parent&: Move assignment operator.

auto GetId() const -> const std::string&: Return the id of the parent entity.

auto GetName() const -> const std::string&: Return the name of the parent entity.

auto GetDescription() const -> const std::string&: Return the description of the parent entity.

auto SetId(const std::string &id) -> void: Set the id of the parent.

auto SetName(const std::string &name) -> void: Set the name of the parent.

Friends

friend class Entity

friend class Parents

friend class RepeatedPtrFieldWrapper< Parent, ProtoParent >

class Parents : public caosdb::entity::RepeatedPtrFieldWrapper<Parent, ProtoParent>

#include <entity.h>

Container for parents of entities.

Should only be instantiated and write-accessed by the owning entity.

Private Functions

inline Parents()

inline explicit Parents(::google::protobuf::RepeatedPtrField<caosdb::entity::v1::Parent> *wrapped)

Friends

friend class Entity

class Property : public caosdb::utility::ScalarProtoMessageWrapper<ProtoProperty>

#include <entity.h>

Property of an Entity.

This is a property which belongs to another entity. Don’t confuse it with an Entity with the “Property” role.

Public Functions

inline Property(const Property &other): Copy constructor.

inline Property(Property &&other): Move constructor.

inline explicit Property(ProtoProperty *other)

inline Property()

~Property() = default

auto GetId() const -> const std::string&: Return the id of this property

auto GetName() const -> const std::string&: Return the name of this property

auto GetDescription() const -> const std::string&: Return the description of this property

auto GetImportance() const -> Importance : Return the importance of this property

auto GetValue() const -> const Value&: Return the value of this property

auto GetUnit() const -> const std::string&: Return the unit of this property

auto GetDataType() const -> const DataType&: Return the datatype of this property

auto SetId(const std::string &id) -> void: Set the id of this property.

auto SetName(const std::string &name) -> void: Set the name of this property.

auto SetDescription(const std::string &description) -> void: Set the description of this property.

auto SetImportance(Importance importance) -> void: Set the importance of this property.

auto SetValue(const Value &value) -> StatusCode : Set the value of this property.

auto SetValue(const AbstractValue &value) -> StatusCode 

auto SetValue(const std::string &value) -> StatusCode 

auto SetValue(const char *value) -> StatusCode 

auto SetValue(const double value) -> StatusCode 

auto SetValue(const std::vector<std::string> &values) -> StatusCode 

auto SetValue(const std::vector<char*> &values) -> StatusCode 

auto SetValue(const std::vector<int64_t> &values) -> StatusCode 

auto SetValue(const std::vector<int> &values) -> StatusCode 

auto SetValue(const std::vector<double> &values) -> StatusCode 

auto SetValue(const std::vector<bool> &values) -> StatusCode 

auto SetValue(const int64_t value) -> StatusCode 

auto SetValue(const int value) -> StatusCode 

auto SetValue(const bool value) -> StatusCode 

auto SetUnit(const std::string &unit) -> void: Set the unit of this property.

auto SetDataType(const DataType &new_data_type) -> StatusCode : Set the datatype of this property.

auto SetDataType(const AtomicDataType new_data_type, bool list_type = false) -> StatusCode 

auto SetDataType(const std::string &new_data_type, bool list_type = false) -> StatusCode 

inline auto operator=(const Property &other) -> Property&: Copy assignment operator.

inline auto operator=(Property &&other) -> Property&: Move assignment operator.

Private Members

Value value

DataType data_type

Friends

friend class Entity

friend class Properties

friend class RepeatedPtrFieldWrapper< Property, ProtoProperty >

class Properties : public caosdb::entity::RepeatedPtrFieldWrapper<Property, ProtoProperty>

#include <entity.h>

Container for Properties of Entities.

Should only be instantiated and write-accessed by the owning entity.

Note that iterating over the Property contents only works via references, since the Property copy constructor is deliberately disabled:

// Accessing single properties as reference
auto &property = my_properties.at(0);
// Iterating via reference
for (auto &property : my_properties) {...}

Private Functions

inline Properties()

inline explicit Properties(RepeatedPtrField<ProtoProperty> *wrapped)

Friends

friend class Entity

class Entity : public caosdb::utility::ScalarProtoMessageWrapper<ProtoEntity>

#include <entity.h>

Entity is the central and basic data object of CaosDB.

This class is a wrapper of the Entity class auto-generated by protobuf (henceforth “ProtoEntity”).

Overview of the Constructors:

Entity() - Calls Entity(ProtoEntity *) with a fresh ProtoEntity Entity(const Entity&) - Copy constructor, calls Entity(ProtoEntity *) after copying wrapped ProtoEntity of the original, then also copies all Messages. Entity(ProtoEntity *) - The workhorse of the constructors. Initializes everything and does not call other Entity constructors. Entity(EntityResponse *) - Constructor which is used by the Transaction class to create an Entity from the server’s response, calls Entity(ProtoEntity). Entity(IdResponse *) - Constructor which is used by the Transaction class to create an Entity from the servers’s response. calls Entity(), then moves the data to the wrapped ProtoEntity. Entity(Entity&&) - Move constructor, calls Entity(ProtoEntity *), then moves the messages and resets the original,

Public Functions

inline Entity(const Entity &original): Copy constructor.

inline explicit Entity(ProtoEntity *other)

inline explicit Entity(EntityResponse *response)

inline explicit Entity(IdResponse *id_response)

inline explicit Entity()

~Entity() = default

inline explicit Entity(Entity &&original): Move constructor.

inline auto operator=(Entity &&other) -> Entity&: Move assignment operator.

inline auto operator=(const Entity &other) -> Entity&: Copy assignment operator.

inline auto GetId() const noexcept -> const std::string&

inline auto HasId() const noexcept -> bool

inline auto GetVersionId() const -> const std::string&

inline auto GetRole() const -> Role 

inline auto GetName() const -> const std::string&

inline auto GetDescription() const -> const std::string&

inline auto GetDataType() const -> const DataType&

inline auto GetUnit() const -> const std::string&

inline auto GetValue() const -> const Value&

auto GetParents() const -> const Parents&

auto GetProperties() const -> const Properties&

inline auto GetErrors() const -> const Messages&

inline auto HasErrors() const -> bool

inline auto GetWarnings() const -> const Messages&

inline auto HasWarnings() const -> bool

inline auto GetInfos() const -> const Messages&

inline auto HasInfos() const -> bool

auto SetRole(Role role) -> void

auto SetName(const std::string &name) -> void

auto SetDescription(const std::string &description) -> void: Set the description of this entity.

auto SetValue(const AbstractValue &value) -> StatusCode 

auto SetValue(const Value &value) -> StatusCode 

auto SetValue(const std::string &value) -> StatusCode 

auto SetValue(const char *value) -> StatusCode 

auto SetValue(const double value) -> StatusCode 

auto SetValue(const std::vector<std::string> &values) -> StatusCode 

auto SetValue(const std::vector<char*> &values) -> StatusCode 

auto SetValue(const std::vector<int64_t> &values) -> StatusCode 

auto SetValue(const std::vector<int> &values) -> StatusCode 

auto SetValue(const std::vector<double> &values) -> StatusCode 

auto SetValue(const std::vector<bool> &values) -> StatusCode 

auto SetValue(const int64_t value) -> StatusCode 

auto SetValue(const int value) -> StatusCode 

auto SetValue(const bool value) -> StatusCode 

auto SetUnit(const std::string &unit) -> void

auto SetDataType(const DataType &new_data_type) -> StatusCode 

auto SetDataType(const AtomicDataType new_data_type, bool list_type = false) -> StatusCode 

auto SetDataType(const std::string &new_data_type, bool list_type = false) -> StatusCode 

auto AppendProperty(const Property &property) -> void

auto RemoveProperty(int index) -> void

auto AppendParent(const Parent &parent) -> void

auto RemoveParent(int index) -> void

auto CopyTo(ProtoEntity *target) -> void: Copy all of this entity’s features to the target ProtoEntity.

auto SetFilePath(const std::string &path) -> void

inline auto HasFile() const -> bool

inline auto SetFileTransmissionId(FileTransmissionId *file_transmission_id) -> void

inline auto GetFileDescriptor() -> FileDescriptor&

inline auto GetLocalPath() const noexcept -> const std::filesystem::path&

inline auto SetLocalPath(const std::filesystem::path &local_path) noexcept -> StatusCode 

inline auto ClearMessages() noexcept -> void

inline auto operator==(const Entity &other) const noexcept -> bool

Return true if the other entity is equal to to this entity.

This method ignores the errors, warnings and info messages.

Private Functions

auto SetId(const std::string &id) -> void

auto SetVersionId(const std::string &id) -> void

inline auto GetArena() const -> Arena*

Private Members

FileDescriptor file_descriptor

Properties properties

Parents parents

Messages errors

Messages warnings

Messages infos

Value value

DataType data_type

Private Static Functions

static auto CreateMessagesField() -> RepeatedPtrField<ProtoMessage>*