#include <esp/core/managedContainers/ManagedFileBasedContainer.h>
template<class T, ManagedObjectAccess Access>
esp::core::managedContainers::ManagedFileBasedContainer class

Class template defining file-io-based responsibilities and functionality for managing esp::core::managedContainers::AbstractFileBasedManagedObject constructs.

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

Base classes

template<class T, ManagedObjectAccess Access>
class ManagedContainer<T, Access>
Class template defining responsibilities and functionality for managing esp::core::managedContainers::AbstractManagedObject constructs.

Derived classes

template<class T, ManagedObjectAccess Access>
class esp::metadata::managers::AbstractAttributesManager
Class template defining responsibilities and functionality for managing esp::metadata::attributes::AbstractAttributes constructs.
template<class T, ManagedObjectAccess Access>
class esp::metadata::managers::AbstractAttributesManager
Class template defining responsibilities and functionality for managing esp::metadata::attributes::AbstractAttributes constructs.
template<class T, ManagedObjectAccess Access>
class esp::metadata::managers::AbstractAttributesManager
Class template defining responsibilities and functionality for managing esp::metadata::attributes::AbstractAttributes constructs.
template<class T, ManagedObjectAccess Access>
class esp::metadata::managers::AbstractAttributesManager
Class template defining responsibilities and functionality for managing esp::metadata::attributes::AbstractAttributes constructs.
template<class T, ManagedObjectAccess Access>
class esp::metadata::managers::AbstractAttributesManager
Class template defining responsibilities and functionality for managing esp::metadata::attributes::AbstractAttributes constructs.
template<class T, ManagedObjectAccess Access>
class esp::metadata::managers::AbstractAttributesManager
Class template defining responsibilities and functionality for managing esp::metadata::attributes::AbstractAttributes constructs.
template<class T, ManagedObjectAccess Access>
class esp::metadata::managers::AbstractAttributesManager
Class template defining responsibilities and functionality for managing esp::metadata::attributes::AbstractAttributes constructs.
template<class T, ManagedObjectAccess Access>
class esp::metadata::managers::AbstractAttributesManager
Class template defining responsibilities and functionality for managing esp::metadata::attributes::AbstractAttributes constructs.
template<class T, ManagedObjectAccess Access>
class esp::metadata::managers::AbstractAttributesManager
Class template defining responsibilities and functionality for managing esp::metadata::attributes::AbstractAttributes constructs.
template<class T, ManagedObjectAccess Access>
class esp::metadata::managers::AbstractAttributesManager
Class template defining responsibilities and functionality for managing esp::metadata::attributes::AbstractAttributes constructs.
template<class T, ManagedObjectAccess Access>
class esp::metadata::managers::AbstractAttributesManager
Class template defining responsibilities and functionality for managing esp::metadata::attributes::AbstractAttributes constructs.

Public types

using ManagedFileIOPtr = std::shared_ptr<T>

Constructors, destructors, conversion operators

ManagedFileBasedContainer(const std::string& metadataType, const std::string& JSONTypeExt) explicit

Public functions

auto createObjectFromJSONFile(const std::string& filename, bool registerObject = true) -> ManagedFileIOPtr
Creates an instance of a managed object from a JSON file, by first loading the file into a JsonDocument and then parsing that document via buildManagedObjectFromDoc.
auto createObjectFromJSONString(const std::string& docName, const std::string& docString, bool registerObject = true) -> ManagedFileIOPtr
Creates an instance of a managed object from a JSON string.
template<typename U>
auto buildManagedObjectFromDoc(const std::string& filename, const U& config) -> ManagedFileIOPtr
Method to load a Managed Object's data from a file. If the file type is not supported by specialization of this method, this method executes and an error is thrown.
auto buildManagedObjectFromDoc(const std::string& filename, const io::JsonGenericValue& jsonConfig) -> ManagedFileIOPtr
Method to load a Managed Object's data from a file. This is the JSON specialization, using type inference.
auto buildObjectFromJSONDoc(const std::string& filename, const io::JsonGenericValue& jsonConfig) -> ManagedFileIOPtr pure virtual
Parse passed JSON Document specifically for ManagedPtr object. It always returns a ManagedPtr object.
auto saveManagedObjectToFile(const std::string& objectHandle, bool overwrite) const -> bool
Saves the esp::core::managedContainers::AbstractFileBasedManagedObject with handle objectHandle to a JSON file using a non-colliding version (if overwrite is false) of the object's handle, with appropriate extension denoting type of JSON, as file name, to the esp::core::managedContainers::AbstractFileBasedManagedObject's specified file directory.
auto saveManagedObjectToFile(const ManagedFileIOPtr& managedObject, bool overwrite) const -> bool
Saves the passed managedObject to a JSON file using a non-colliding version (if overwrite is false) of the object's handle, with appropriate extension denoting type of JSON, as file name, to the esp::core::managedContainers::AbstractFileBasedManagedObject's specified file directory.
auto saveManagedObjectToFile(const std::string& objectHandle, const std::string& fullFilename) const -> bool
Saves the esp::core::managedContainers::AbstractFileBasedManagedObject with handle objectHandle to a JSON file using the specified, fully-qualified fullFilename, with appropriate type extension appended if not present. Will overwrite any file with same name found.
auto saveManagedObjectToFile(const ManagedFileIOPtr& managedObject, const std::string& filename, bool createDir) const -> bool
Saves the passed managedObject to a JSON file using the specified filename, with appropriate type extension appended if not present. Will overwrite any file with same name found. If the directory component is not specified in the filename, will use the source directory of the managedObject specified.
auto saveManagedObjectToFile(const ManagedFileIOPtr& managedObject, const std::string& fileDirectory, const std::string& fileName, bool createDir) const -> bool
Saves the passed managedObject to a JSON file using the specified, fully-qualified fullFilename, with appropriate type extension appended if not present. Will overwrite any file with same name found.
auto getFormattedJSONFileName(const std::string& filename) -> std::string
Return a properly formated JSON file name for the esp::core::managedContainers::AbstractFileBasedManagedObject managed by this manager. This will change the extension to the appropriate json extension.
auto getJSONTypeExt() const -> std::string
Returns the config file type and file extension used for the files that build the esp::core::managedContainers::AbstractFileBasedManagedObject managed by this manager.

Protected functions

auto findFilenameUsingCriteria(const std::string& srcFilename, const std::vector<std::string>& extensions) const -> std::string
Returns true if candidate files are found by constructing filenames based on srcFilename and extensions . Returns the first fully qualified filename candidate that is found, if one exists, or an empty string if not. This is provided to assist in synthesizing default filenames that can be expected to exist.
auto saveManagedObjectToFileInternal(const ManagedFileIOPtr& managedObject, const std::string& fullFilename) const -> bool
Saves managedObject to a JSON file using the given fileName in the given fileDirectory .
template<class U>
auto verifyLoadDocument(const std::string& filename, std::unique_ptr<U>& resDoc) -> bool
Verify passd filename is legal document of type U. Returns loaded document in passed argument if successful. This requires appropriate specialization for each type name, so if this specific method is executed it means no appropriate specialization exists for passed type of document.
auto verifyLoadDocument(const std::string& filename, std::unique_ptr<io::JsonDocument>& jsonDoc) -> bool
Verify passed filename is legal json document, return loaded document or nullptr if fails.
template<class U>
auto verifyParseDocString(const std::string& docName, const std::string& docString, std::unique_ptr<U>& resDoc) -> bool
Verify passd docString represents a legal document of type U. Returns parsed document in passed argument resDoc if successful. This requires appropriate specialization for each type name/type of destination document, so if this specific method is executed it means no appropriate specialization exists for passed type U of document.
auto verifyParseDocString(const std::string& docName, const std::string& docString, std::unique_ptr<io::JsonDocument>& jsonDoc) -> bool
Verify passed docString , referenced by docName is a valid json document, return parsed document or nullptr if fails.
auto convertFilenameToPassedExt(const std::string& filename, const std::string& fileTypeExt) -> std::string
Will build a new file name for filename by replacing the existing extension(s) with the passed fileTypeExt, if it is missing. NOTE : this does not verify that file exists.
void setFileDirectoryFromHandle(ManagedFileIOPtr object)
Get directory component of managed object handle and call esp::core::managedContainers::AbstractFileBasedManagedObject::setFileDirectory if a legitimate directory exists in handle.

Protected variables

const std::string JSONTypeExt_
The string extension for the JSON configuration file backing this Manager's esp::core::managedContainers::AbstractFileBasedManagedObject including the json extension.

Function documentation

template<class T, ManagedObjectAccess Access>
ManagedFileIOPtr esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::createObjectFromJSONFile(const std::string& filename, bool registerObject = true)

Creates an instance of a managed object from a JSON file, by first loading the file into a JsonDocument and then parsing that document via buildManagedObjectFromDoc.

Parameters
filename the name of the file describing the object managed object. Assumes it exists and fails if it does not.
registerObject whether to add this managed object to the library. If the user is going to edit this managed object, this should be false - any subsequent editing will require re-registration. Defaults to true.
Returns a reference to the desired managed object, or nullptr if fails.

template<class T, ManagedObjectAccess Access>
ManagedFileIOPtr esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::createObjectFromJSONString(const std::string& docName, const std::string& docString, bool registerObject = true)

Creates an instance of a managed object from a JSON string.

Parameters
docName name of potential document to load
docString string of data expected to be in the expected format. Assumes this is a valid JSON string, and fails if it is not.
registerObject whether to add this managed object to the library. If the user is going to edit this managed object, this should be false - any subsequent editing will require re-registration. Defaults to true.
Returns a reference to the desired managed object, or nullptr if fails.

template<class T, ManagedObjectAccess Access> template<typename U>
ManagedFileIOPtr esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::buildManagedObjectFromDoc(const std::string& filename, const U& config)

Method to load a Managed Object's data from a file. If the file type is not supported by specialization of this method, this method executes and an error is thrown.

Parameters
filename name of file document to load from
config document to read for data
Returns a shared pointer of the created Managed Object

template<class T, ManagedObjectAccess Access>
ManagedFileIOPtr esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::buildManagedObjectFromDoc(const std::string& filename, const io::JsonGenericValue& jsonConfig)

Method to load a Managed Object's data from a file. This is the JSON specialization, using type inference.

Parameters
filename name of file document to load from
jsonConfig
Returns a shared pointer of the created Managed Object

template<class T, ManagedObjectAccess Access>
ManagedFileIOPtr esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::buildObjectFromJSONDoc(const std::string& filename, const io::JsonGenericValue& jsonConfig) pure virtual

Parse passed JSON Document specifically for ManagedPtr object. It always returns a ManagedPtr object.

Parameters
filename The name of the file describing the ManagedPtr, used as managed object handle/name on create.
jsonConfig json document to parse - assumed to be legal JSON doc.
Returns a reference to the desired managed object.

template<class T, ManagedObjectAccess Access>
bool esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::saveManagedObjectToFile(const std::string& objectHandle, bool overwrite) const

Saves the esp::core::managedContainers::AbstractFileBasedManagedObject with handle objectHandle to a JSON file using a non-colliding version (if overwrite is false) of the object's handle, with appropriate extension denoting type of JSON, as file name, to the esp::core::managedContainers::AbstractFileBasedManagedObject's specified file directory.

Parameters
objectHandle The name of the object to save. If not found, returns false.
overwrite Whether or not an existing json file with the same name should be overwritten.
Returns Whether save was successful

template<class T, ManagedObjectAccess Access>
bool esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::saveManagedObjectToFile(const ManagedFileIOPtr& managedObject, bool overwrite) const

Saves the passed managedObject to a JSON file using a non-colliding version (if overwrite is false) of the object's handle, with appropriate extension denoting type of JSON, as file name, to the esp::core::managedContainers::AbstractFileBasedManagedObject's specified file directory.

Parameters
managedObject Theobject to save.
overwrite Whether or not an existing json file with the same name should be overwritten.
Returns Whether save was successful

template<class T, ManagedObjectAccess Access>
bool esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::saveManagedObjectToFile(const std::string& objectHandle, const std::string& fullFilename) const

Saves the esp::core::managedContainers::AbstractFileBasedManagedObject with handle objectHandle to a JSON file using the specified, fully-qualified fullFilename, with appropriate type extension appended if not present. Will overwrite any file with same name found.

Parameters
objectHandle The name of the object to save. If not found, returns false.
fullFilename The name of the file to save to. Will overwrite any file that has the same name.
Returns Whether save was successful

template<class T, ManagedObjectAccess Access>
bool esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::saveManagedObjectToFile(const ManagedFileIOPtr& managedObject, const std::string& filename, bool createDir) const

Saves the passed managedObject to a JSON file using the specified filename, with appropriate type extension appended if not present. Will overwrite any file with same name found. If the directory component is not specified in the filename, will use the source directory of the managedObject specified.

Parameters
managedObject The object to save.
filename The name of the file to save to. Will overwrite any file that has the same name.
createDir Whether to create the destination directory if DNE.
Returns Whether save was successful

template<class T, ManagedObjectAccess Access>
bool esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::saveManagedObjectToFile(const ManagedFileIOPtr& managedObject, const std::string& fileDirectory, const std::string& fileName, bool createDir) const

Saves the passed managedObject to a JSON file using the specified, fully-qualified fullFilename, with appropriate type extension appended if not present. Will overwrite any file with same name found.

Parameters
managedObject The object to save.
fileDirectory The destination directory to save the new file.
fileName The name of the file to save to - may contain relative path information. Will overwrite any file that has the same name in the given destination directory.
createDir Whether to create the destination directory if DNE.
Returns Whether save was successful

template<class T, ManagedObjectAccess Access>
std::string esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::getFormattedJSONFileName(const std::string& filename)

Return a properly formated JSON file name for the esp::core::managedContainers::AbstractFileBasedManagedObject managed by this manager. This will change the extension to the appropriate json extension.

Parameters
filename The original filename
Returns a candidate JSON file name for the esp::core::managedContainers::AbstractFileBasedManagedObject managed by this manager.

template<class T, ManagedObjectAccess Access>
std::string esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::findFilenameUsingCriteria(const std::string& srcFilename, const std::vector<std::string>& extensions) const protected

Returns true if candidate files are found by constructing filenames based on srcFilename and extensions . Returns the first fully qualified filename candidate that is found, if one exists, or an empty string if not. This is provided to assist in synthesizing default filenames that can be expected to exist.

Parameters
srcFilename The source file name to use as a base to build filename candidates.
extensions A list of extensions to search for
Returns The fully-qualified filename found to match passed criteria, if exists, or the empty string if not.

template<class T, ManagedObjectAccess Access>
bool esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::saveManagedObjectToFileInternal(const ManagedFileIOPtr& managedObject, const std::string& fullFilename) const protected

Saves managedObject to a JSON file using the given fileName in the given fileDirectory .

Parameters
managedObject The name of the object to save. If not found, returns false.
fullFilename The fully-qualified filename to save to.
Returns Whether save was successful

template<class T, ManagedObjectAccess Access> template<class U>
bool esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::verifyLoadDocument(const std::string& filename, std::unique_ptr<U>& resDoc) protected

Verify passd filename is legal document of type U. Returns loaded document in passed argument if successful. This requires appropriate specialization for each type name, so if this specific method is executed it means no appropriate specialization exists for passed type of document.

Parameters
filename name of potential document to load
resDoc a reference to the document to be loaded into.
Returns whether document has been loaded successfully or not

template<class T, ManagedObjectAccess Access>
bool esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::verifyLoadDocument(const std::string& filename, std::unique_ptr<io::JsonDocument>& jsonDoc) protected

Verify passed filename is legal json document, return loaded document or nullptr if fails.

Parameters
filename name of potential json document to load
jsonDoc a reference to the json document to be parsed
Returns whether document has been loaded successfully or not

template<class T, ManagedObjectAccess Access> template<class U>
bool esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::verifyParseDocString(const std::string& docName, const std::string& docString, std::unique_ptr<U>& resDoc) protected

Verify passd docString represents a legal document of type U. Returns parsed document in passed argument resDoc if successful. This requires appropriate specialization for each type name/type of destination document, so if this specific method is executed it means no appropriate specialization exists for passed type U of document.

Parameters
docName name of potential document to load
docString string of data expected to be in the expected format of documents of type U
resDoc a reference to the document the @docString should be parsed into.
Returns whether document has been parsed successfully or not

template<class T, ManagedObjectAccess Access>
bool esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::verifyParseDocString(const std::string& docName, const std::string& docString, std::unique_ptr<io::JsonDocument>& jsonDoc) protected

Verify passed docString , referenced by docName is a valid json document, return parsed document or nullptr if fails.

Parameters
docName name of potential json document to parse from docString
docString string of JSON to attempt to parse
jsonDoc a reference to the json document to be parsed
Returns whether document has been loaded successfully or not

template<class T, ManagedObjectAccess Access>
std::string esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::convertFilenameToPassedExt(const std::string& filename, const std::string& fileTypeExt) protected

Will build a new file name for filename by replacing the existing extension(s) with the passed fileTypeExt, if it is missing. NOTE : this does not verify that file exists.

Parameters
filename The original file name
fileTypeExt The extension to use for the new filename.
Returns The file name changed so that it has the correct fileTypeExt if it was missing.

template<class T, ManagedObjectAccess Access>
void esp::core::managedContainers::ManagedFileBasedContainer<T, Access>::setFileDirectoryFromHandle(ManagedFileIOPtr object) protected

Get directory component of managed object handle and call esp::core::managedContainers::AbstractFileBasedManagedObject::setFileDirectory if a legitimate directory exists in handle.

Parameters
object pointer to managed object to set