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

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

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

Contents

Base classes

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

Derived classes

template<class T, core::ManagedObjectAccess Access>
class esp::metadata::managers::AttributesManager
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.
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) -> bool
Saves the esp::core::AbstractFileBasedManagedObject with handle objectHandle to a JSON file using a non-colliding version (if overwrite is false) the object's handle, with appropriate extension denoting type of JSON, as file name, to the esp::core::AbstractFileBasedManagedObject's specified file directory.
auto saveManagedObjectToFile(const std::string& objectHandle, const std::string& fullFilename) -> bool
Saves the esp::core::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 getFormattedJSONFileName(const std::string& filename) -> std::string
Return a properly formated JSON file name for the esp::core::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::AbstractFileBasedManagedObject managed by this manager.

Protected functions

auto saveManagedObjectToFileInternal(const ManagedFileIOPtr& managedObject, const std::string& filename, const std::string& fileDirectory) const -> bool pure virtual
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 T. Returns loaded document in passed argument if successful. This requires appropriate specialization for each type name, so if this 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.
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::AbstractManagedObject::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::ManagedFileBasedContainer<T, Access>::createObjectFromJSONFile(const std::string& filename, bool registerObject = true)

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

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> template<typename U>
ManagedFileIOPtr esp::core::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::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::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::ManagedFileBasedContainer<T, Access>::saveManagedObjectToFile(const std::string& objectHandle, bool overwrite)

Saves the esp::core::AbstractFileBasedManagedObject with handle objectHandle to a JSON file using a non-colliding version (if overwrite is false) the object's handle, with appropriate extension denoting type of JSON, as file name, to the esp::core::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::ManagedFileBasedContainer<T, Access>::saveManagedObjectToFile(const std::string& objectHandle, const std::string& fullFilename)

Saves the esp::core::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>
std::string esp::core::ManagedFileBasedContainer<T, Access>::getFormattedJSONFileName(const std::string& filename)

Return a properly formated JSON file name for the esp::core::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::AbstractFileBasedManagedObject managed by this manager.

template<class T, ManagedObjectAccess Access>
bool esp::core::ManagedFileBasedContainer<T, Access>::saveManagedObjectToFileInternal(const ManagedFileIOPtr& managedObject, const std::string& filename, const std::string& fileDirectory) const pure virtual 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.
filename The filename of the file to save to.
fileDirectory The directory to save to. If the directory does not exist, will return false.
Returns Whether save was successful

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

Verify passd filename is legal document of type T. Returns loaded document in passed argument if successful. This requires appropriate specialization for each type name, so if this 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 parsed.
Returns whether document has been loaded successfully or not

template<class T, ManagedObjectAccess Access>
bool esp::core::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>
std::string esp::core::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::ManagedFileBasedContainer<T, Access>::setFileDirectoryFromHandle(ManagedFileIOPtr object) protected

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

Parameters
object pointer to managed object to set