caosdb/entity.h

Anything entity-related.

Author

Timm Fitchen

Date

2021-07-07

namespace caosdb::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::v1alpha1::Parent
using ProtoProperty = caosdb::entity::v1alpha1::Property
using ProtoEntity = caosdb::entity::v1alpha1::Entity
using ProtoFileDescriptor = caosdb::entity::v1alpha1::FileDescriptor
using ProtoMessage = caosdb::entity::v1alpha1::Message
typedef caosdb::entity::v1alpha1::Value ProtoValue
using ProtoImportance = caosdb::entity::v1alpha1::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"}}
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(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.

Public Functions

inline Entity(const Entity &original)
inline explicit Entity(ProtoEntity *other)
inline explicit Entity(EntityResponse *response)
inline explicit Entity(IdResponse *id_response)
inline explicit Entity()
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
auto SetFileTransmissionRegistrationId(const std::string &registration_id) -> void
inline auto SetFileTransmissionId(FileTransmissionId *file_transmission_id) -> void
inline auto GetFileDescriptor() -> FileDescriptor&
inline auto GetLocalPath() const noexcept -> const boost::filesystem::path&
inline auto SetLocalPath(const boost::filesystem::path &local_path) noexcept -> StatusCode
inline auto ClearMessages() noexcept -> void

Private Functions

inline auto GetNextFileId() -> std::string
auto SetId(const std::string &id) -> void
auto SetVersionId(const std::string &id) -> void

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>*
struct FileDescriptor

Public Members

FileTransmissionId *file_transmission_id
ProtoFileDescriptor *wrapped
boost::filesystem::path local_path
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.

Public Functions

~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()
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.

Public Functions

~Parents() = default

Private Functions

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

Friends

friend class Entity
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) {...}

Public Functions

~Properties() = default

Private Functions

inline Properties()
inline explicit Properties(RepeatedPtrField<ProtoProperty> *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()
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 >
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.

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