template<class T, ManagedObjectAccess Access>
esp::core::ManagedContainer class

Class template defining responsibilities and functionality for managing esp::core::AbstractManagedObject constructs.

Template parameters
T the type of managed object a particular specialization of this class works with. Must inherit from esp::core::AbstractManagedObject.
Access Whether the default access (getters) for this container provides copies of the objects held, or the actual objects themselves.

Base classes

class ManagedContainerBase
Base class of Managed Container, holding template-type-independent functionality.

Derived classes

template<class T, ManagedObjectAccess Access>
class ManagedFileBasedContainer
Class template defining file-io-based responsibilities and functionality for managing esp::core::AbstractFileBasedManagedObject constructs.

Public types

using ManagedPtr = std::shared_ptr<T>
Alias for shared pointer to the esp::core::AbstractManagedObject this container manages.

Constructors, destructors, conversion operators

ManagedContainer(const std::string& metadataType) explicit
Constructor.

Public functions

auto createObject(const std::string& objectHandle, bool registerObject = true) -> ManagedPtr pure virtual
Creates an instance of a managed object described by passed string.
auto createDefaultObject(const std::string& objectName, bool registerObject = false) -> ManagedPtr
Creates an instance of a managed object holding default values.
auto registerObject(ManagedPtr managedObject, const std::string& objectHandle = "", bool forceRegistration = false) -> int
Add a copy of esp::core::AbstractManagedObject to the objectLibrary_.
auto getObjectByID(int managedObjectID) const -> ManagedPtr
Get a reference to the managed object identified by the managedObjectID. Should only be used internally - Users should only ever access copies of managed objects, unless this managed container's Access policy is Share.
auto getObjectByHandle(const std::string& objectHandle) const -> ManagedPtr
Get a reference to the managed object identified by the passed objectHandle. Should only be used internally - Users should only ever access copies of managed objects, unless this managed container's Access policy is Share.
auto getObjectsByHandleSubstring(const std::string& subStr = "", bool contains = true) -> std::unordered_map<std::string, ManagedPtr>
Retrieve a map of key= std::string handle; value = copy of ManagedPtr object where the handles match the passed . See ManagedContainerBase::getObjectHandlesBySubStringPerType.
template<class U>
auto getObjectsByHandleSubstring(const std::string& subStr = "", bool contains = true) -> std::unordered_map<std::string, std::shared_ptr<U>>
Templated version. Retrieve a map of key= std::string handle; value = copy of ManagedPtr object where the handles match the passed . See ManagedContainerBase::getObjectHandlesBySubStringPerType.
auto removeObjectByID(int objectID) -> ManagedPtr
Remove the managed object referenced by the passed string handle. Will emplace managed object ID within deque of usable IDs and return the managed object being removed.
auto removeObjectByHandle(const std::string& objectHandle) -> ManagedPtr
Remove the managed object referenced by the passed string handle. Will emplace managed object ID within deque of usable IDs and return the managed object being removed.
auto removeAllObjects() -> std::vector<ManagedPtr>
Remove all managed objects that have not been marked as default/non-removable, and return a vector of the managed objects removed.
auto removeObjectsBySubstring(const std::string& subStr = "", bool contains = true) -> std::vector<ManagedPtr>
Remove managed objects that contain passed substring and that have not been marked as default/non-removable, and return a vector of the managed objects removed.
auto getObjectOrCopyByID(int managedObjectID) -> ManagedPtr
Get a reference to, or a copy of, the managed object identified by the managedObjectID, depending on Access value. This is the function that should be be accessed by the user for general object consumption by ID.
auto getObjectOrCopyByHandle(const std::string& objectHandle) -> ManagedPtr
Get a reference to, or a copy of, the managed object identified by the objectHandle, depending on Access value. This is the function that should be be accessed by the user for general object consumption by Handle.
template<class U>
auto getObjectOrCopyByID(int managedObjectID) -> std::shared_ptr<U>
Get a reference to, or a copy of, the managed object identified by the managedObjectID, depending on Access value, and casted to the appropriate derived managed object class. This is the version that should be accessed by the user for type-casted object consumption by ID.
template<class U>
auto getObjectOrCopyByHandle(const std::string& objectHandle) -> std::shared_ptr<U>
Get a reference to, or a copy of, the managed object identified by the managedObjectID, depending on Access value, and casted to the appropriate derived managed object class. This is the version that should be accessed by the user for type-casted object consumption by Handle.
auto getObjectCopyByID(int managedObjectID) -> ManagedPtr
Get a reference to a copy of the managed object identified by the managedObjectID.
auto getObjectCopyByHandle(const std::string& objectHandle) -> ManagedPtr
Get a reference to a copy of the object specified by objectHandle.
template<class U>
auto getObjectCopyByID(int managedObjectID) -> std::shared_ptr<U>
Get a reference to a copy of the managed object identified by the managedObjectID, casted to the appropriate derived managed object class.
template<class U>
auto getObjectCopyByHandle(const std::string& objectHandle) -> std::shared_ptr<U>
Get a reference to a copy of the object specified by objectHandle , casted to the appropriate derived managed object class.
void setDefaultObject(ManagedPtr& _defaultObj) virtual
Set the object to provide default values upon construction of esp::core::AbstractManagedObject. Override if object should not have defaults.
void clearDefaultObject()
Clear any default objects used for construction.

Protected types

using Map_Of_CopyCtors = std::unordered_map<std::string, ManagedPtr(ManagedContainer<T, Access>::*)(ManagedPtr&)>
Define a map type referencing function pointers to createObjectCopy keyed by string names of classes being instanced,.

Protected functions

auto postCreateRegister(ManagedPtr object, bool doRegistration) -> ManagedPtr
Perform post creation registration if specified.
auto initNewObjectInternal(const std::string& objectHandle, bool builtFromConfig) -> ManagedPtr pure virtual
Used Internally. Create and configure newly-created managed object with any default values, before any specific values are set.
auto removeObjectInternal(int objectID, const std::string& objectHandle, const std::string& src) -> ManagedPtr
Used Internally. Remove the managed object referenced by the passed string handle. Will emplace managed object ID within deque of usable IDs and return the managed object being removed.
auto registerObjectFinalize(ManagedPtr object, const std::string& objectHandle, bool forceRegistration) -> int pure virtual
implementation of managed object type-specific registration
template<typename U>
auto createObjectCopy(ManagedPtr& orig) -> ManagedPtr
Build a shared pointer to a copy of a the passed managed object, of appropriate managed object type for passed object type. This is the function called by the copy constructor map.
auto copyObject(ManagedPtr& origAttr) -> ManagedPtr
Build an esp::core::AbstractManagedObject object of type associated with passed object.
auto constructFromDefault(const std::string& newHandle) -> ManagedPtr
Create a new object as a copy of defaultObject_ if it exists, otherwise return nullptr.
auto addObjectToLibrary(ManagedPtr object, const std::string& objectHandle) -> int
add passed managed object to library, setting managedObjectID appropriately. Called internally by registerObject.

Protected variables

Map_Of_CopyCtors copyConstructorMap_
Map of function pointers to instantiate a copy of a managed object. A managed object is instanced by accessing the approrpiate function pointer. THIS MUST BE INSTANCED IN SPECIALIZATION CONSTRUCTOR.
ManagedPtr defaultObj_
An object to provide default values, to be used upon AbstractManagedObject construction.

Function documentation

template<class T, ManagedObjectAccess Access>
esp::core::ManagedContainer<T, Access>::ManagedContainer(const std::string& metadataType) explicit

Constructor.

Parameters
metadataType The name of the managed object type.

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::createObject(const std::string& objectHandle, bool registerObject = true) pure virtual

Creates an instance of a managed object described by passed string.

Parameters
objectHandle the origin of the desired managed object to be created.
registerObject whether to add this managed object to the library or not. If the user is going to edit this managed object, this should be false. Defaults to true. If specified as true, then this function returns a copy of the registered managed object.
Returns a reference to the desired managed object.

If a managed object exists with this handle, the existing managed object will be overwritten with the newly created one if registerObject is true.

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::createDefaultObject(const std::string& objectName, bool registerObject = false)

Creates an instance of a managed object holding default values.

Parameters
objectName The desired handle for this managed object.
registerObject whether to add this managed object to the library or not. If the user is going to edit this managed object, this should be false. If specified as true, then this function returns a copy of the registered managed object. Defaults to false. If specified as true, then this function returns a copy of the registered managed object.
Returns a reference to the desired managed object.

If a managed object exists with this handle, the existing managed object will be overwritten with the newly created one if registerObject is true. This method is specifically intended to directly construct an managed object for editing, and so defaults to false for registerObject

template<class T, ManagedObjectAccess Access>
int esp::core::ManagedContainer<T, Access>::registerObject(ManagedPtr managedObject, const std::string& objectHandle = "", bool forceRegistration = false)

Add a copy of esp::core::AbstractManagedObject to the objectLibrary_.

Parameters
managedObject The managed object.
objectHandle The key for referencing the managed object in the ManagedContainerBase::objectLibrary_. Will be set as origin handle for managed object. If empty string, use existing origin handle.
forceRegistration Will register object even if conditional registration checks fail in registerObjectFinalize.
Returns The unique ID of the managed object being registered, or ID_UNDEFINED if failed

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::getObjectByID(int managedObjectID) const

Get a reference to the managed object identified by the managedObjectID. Should only be used internally - Users should only ever access copies of managed objects, unless this managed container's Access policy is Share.

Parameters
managedObjectID The ID of the managed object. Is mapped to the key referencing the asset in ManagedContainerBase::objectLibrary_ .
Returns A mutable reference to the object managed object, or nullptr if does not exist

Can be used to manipulate a managed object before instancing new objects.

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::getObjectByHandle(const std::string& objectHandle) const

Get a reference to the managed object identified by the passed objectHandle. Should only be used internally - Users should only ever access copies of managed objects, unless this managed container's Access policy is Share.

Parameters
objectHandle The key referencing the managed object in objectLibrary_.
Returns A reference to the managed object, or nullptr if does not exist

template<class T, ManagedObjectAccess Access>
std::unordered_map<std::string, ManagedPtr> esp::core::ManagedContainer<T, Access>::getObjectsByHandleSubstring(const std::string& subStr = "", bool contains = true)

Retrieve a map of key= std::string handle; value = copy of ManagedPtr object where the handles match the passed . See ManagedContainerBase::getObjectHandlesBySubStringPerType.

Parameters
subStr substring key to search for within existing managed objects.
contains whether to search for keys containing, or excluding, passed subStr
Returns a map of the objects whose keys match the specified substring search.

template<class T, ManagedObjectAccess Access> template<class U>
std::unordered_map<std::string, std::shared_ptr<U>> esp::core::ManagedContainer<T, Access>::getObjectsByHandleSubstring(const std::string& subStr = "", bool contains = true)

Templated version. Retrieve a map of key= std::string handle; value = copy of ManagedPtr object where the handles match the passed . See ManagedContainerBase::getObjectHandlesBySubStringPerType.

Parameters
subStr substring key to search for within existing managed objects.
contains whether to search for keys containing, or excluding, passed subStr
Returns a map of the objects whose keys match the specified substring search.

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::removeObjectByID(int objectID)

Remove the managed object referenced by the passed string handle. Will emplace managed object ID within deque of usable IDs and return the managed object being removed.

Parameters
objectID The ID of the managed object desired.
Returns the desired managed object being deleted, or nullptr if does not exist

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::removeObjectByHandle(const std::string& objectHandle)

Remove the managed object referenced by the passed string handle. Will emplace managed object ID within deque of usable IDs and return the managed object being removed.

Parameters
objectHandle the string key of the managed object desired.
Returns the desired managed object being deleted, or nullptr if does not exist

template<class T, ManagedObjectAccess Access>
std::vector<ManagedPtr> esp::core::ManagedContainer<T, Access>::removeAllObjects()

Remove all managed objects that have not been marked as default/non-removable, and return a vector of the managed objects removed.

Returns A vector containing all the managed objects that have been removed from the library.

template<class T, ManagedObjectAccess Access>
std::vector<ManagedPtr> esp::core::ManagedContainer<T, Access>::removeObjectsBySubstring(const std::string& subStr = "", bool contains = true)

Remove managed objects that contain passed substring and that have not been marked as default/non-removable, and return a vector of the managed objects removed.

Parameters
subStr substring to search for within existing primitive object managed objects
contains whether to search for keys containing, or excluding, substr
Returns A vector containing all the managed objects that have been removed from the library.

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::getObjectOrCopyByID(int managedObjectID)

Get a reference to, or a copy of, the managed object identified by the managedObjectID, depending on Access value. This is the function that should be be accessed by the user for general object consumption by ID.

Parameters
managedObjectID The ID of the managed object. Is mapped to the key referencing the asset in ManagedContainerBase::objectLibrary_ .
Returns A mutable reference to the managed object, or a copy, or nullptr if does not exist

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::getObjectOrCopyByHandle(const std::string& objectHandle)

Get a reference to, or a copy of, the managed object identified by the objectHandle, depending on Access value. This is the function that should be be accessed by the user for general object consumption by Handle.

Parameters
objectHandle the string key of the managed object desired.
Returns A mutable reference to the managed object, or a copy, or nullptr if does not exist

template<class T, ManagedObjectAccess Access> template<class U>
std::shared_ptr<U> esp::core::ManagedContainer<T, Access>::getObjectOrCopyByID(int managedObjectID)

Get a reference to, or a copy of, the managed object identified by the managedObjectID, depending on Access value, and casted to the appropriate derived managed object class. This is the version that should be accessed by the user for type-casted object consumption by ID.

Parameters
managedObjectID The ID of the managed object. Is mapped to the key referencing the asset in ManagedContainerBase::objectLibrary_.
Returns A mutable reference to the managed object, or a copy, casted to requested type, or nullptr if does not exist

template<class T, ManagedObjectAccess Access> template<class U>
std::shared_ptr<U> esp::core::ManagedContainer<T, Access>::getObjectOrCopyByHandle(const std::string& objectHandle)

Get a reference to, or a copy of, the managed object identified by the managedObjectID, depending on Access value, and casted to the appropriate derived managed object class. This is the version that should be accessed by the user for type-casted object consumption by Handle.

Parameters
objectHandle the string key of the managed object desired.
Returns A mutable reference to the managed object, or a copy, casted to requested type, or nullptr if does not exist

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::getObjectCopyByID(int managedObjectID)

Get a reference to a copy of the managed object identified by the managedObjectID.

Parameters
managedObjectID The ID of the managed object. Is mapped to the key referencing the asset in ManagedContainerBase::objectLibrary_ .
Returns A mutable reference to a copy of the managed object, or nullptr if does not exist

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::getObjectCopyByHandle(const std::string& objectHandle)

Get a reference to a copy of the object specified by objectHandle.

Parameters
objectHandle the string key of the managed object desired.
Returns A mutable reference to a copy of the managed object, or nullptr if does not exist

template<class T, ManagedObjectAccess Access> template<class U>
std::shared_ptr<U> esp::core::ManagedContainer<T, Access>::getObjectCopyByID(int managedObjectID)

Get a reference to a copy of the managed object identified by the managedObjectID, casted to the appropriate derived managed object class.

Parameters
managedObjectID The ID of the managed object. Is mapped to the key referencing the asset in ManagedContainerBase::objectLibrary_.
Returns A mutable reference to a copy of the managed object casted to the requested type, or nullptr if does not exist

template<class T, ManagedObjectAccess Access> template<class U>
std::shared_ptr<U> esp::core::ManagedContainer<T, Access>::getObjectCopyByHandle(const std::string& objectHandle)

Get a reference to a copy of the object specified by objectHandle , casted to the appropriate derived managed object class.

Parameters
objectHandle the string key of the managed object desired.
Returns A mutable reference to a copy of the managed object casted to the requested type, or nullptr if does not exist

template<class T, ManagedObjectAccess Access>
void esp::core::ManagedContainer<T, Access>::setDefaultObject(ManagedPtr& _defaultObj) virtual

Set the object to provide default values upon construction of esp::core::AbstractManagedObject. Override if object should not have defaults.

Parameters
_defaultObj the object to use for defaults;

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::postCreateRegister(ManagedPtr object, bool doRegistration) protected

Perform post creation registration if specified.

Parameters
object The managed object
doRegistration If managed object should be registered
Returns managed object, or null ptr if registration failed.

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::initNewObjectInternal(const std::string& objectHandle, bool builtFromConfig) pure virtual protected

Used Internally. Create and configure newly-created managed object with any default values, before any specific values are set.

Parameters
objectHandle handle name to be assigned to the managed object.
builtFromConfig Managed Object is being constructed from a config file (i.e. objectHandle is config file filename). If false this means Manage Object is being constructed as some kind of new/default.
Returns Newly created but unregistered ManagedObject pointer, with only default values set.

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::removeObjectInternal(int objectID, const std::string& objectHandle, const std::string& src) protected

Used Internally. Remove the managed object referenced by the passed string handle. Will emplace managed object ID within deque of usable IDs and return the managed object being removed.

Parameters
objectID the id of the managed object desired.
objectHandle the string key of the managed object desired.
src String denoting the source of the remove request.
Returns the desired managed object being deleted, or nullptr if does not exist

template<class T, ManagedObjectAccess Access>
int esp::core::ManagedContainer<T, Access>::registerObjectFinalize(ManagedPtr object, const std::string& objectHandle, bool forceRegistration) pure virtual protected

implementation of managed object type-specific registration

Parameters
object the managed object to be registered
objectHandle the name to register the managed object with. Expected to be valid.
forceRegistration Will register object even if conditional registration checks fail.
Returns The unique ID of the managed object being registered, or ID_UNDEFINED if failed

template<class T, ManagedObjectAccess Access> template<typename U>
ManagedPtr esp::core::ManagedContainer<T, Access>::createObjectCopy(ManagedPtr& orig) protected

Build a shared pointer to a copy of a the passed managed object, of appropriate managed object type for passed object type. This is the function called by the copy constructor map.

Parameters
orig original object of type ManagedPtr being copied

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::copyObject(ManagedPtr& origAttr) protected

Build an esp::core::AbstractManagedObject object of type associated with passed object.

Parameters
origAttr The ptr to the original AbstractManagedObject object to copy

template<class T, ManagedObjectAccess Access>
ManagedPtr esp::core::ManagedContainer<T, Access>::constructFromDefault(const std::string& newHandle) protected

Create a new object as a copy of defaultObject_ if it exists, otherwise return nullptr.

Parameters
newHandle the name for the copy of the default.
Returns New object or nullptr

template<class T, ManagedObjectAccess Access>
int esp::core::ManagedContainer<T, Access>::addObjectToLibrary(ManagedPtr object, const std::string& objectHandle) protected

add passed managed object to library, setting managedObjectID appropriately. Called internally by registerObject.

Parameters
object the managed object to add to the library
objectHandle the origin handle/name of the managed object to add. The origin handle of the managed object will be set to this here, in case this managed object is constructed with a different handle.
Returns the managedObjectID of the managed object