SMTK
@SMTK_VERSION@
Simulation Modeling Tool Kit
|
An abstract base class for SMTK resources. More...
#include <Resource.h>
Public Types | |
typedef std::size_t | Index |
typedef smtk::resource::Metadata | Metadata |
typedef detail::ResourceLinks | Links |
typedef detail::ResourceProperties | Properties |
typedef query::Queries | Queries |
Public Member Functions | |
smtkTypeMacro (smtk::resource::Resource) | |
smtkSuperclassMacro (smtk::resource::PersistentObject) | |
smtkSharedFromThisMacro (smtk::resource::PersistentObject) | |
Resource (Resource &&) noexcept | |
Resource Type Introspection | |
Resources provide an integer type-id common to their class definition as well as methods to detect when resources are derived from a common ancestor class. | |
virtual Index | index () const |
Index is a compile-time intrinsic of the derived resource's type; as such, it cannot be set. | |
template<class ResourceType > | |
bool | isOfType () const |
Given a resource type, return whether or not this resource is or is derived from the resource described by the index. | |
virtual bool | isOfType (const Index &index) const |
Given a resource index, return whether or not this resource is or is derived from the resource described by the index. | |
virtual bool | isOfType (const std::string &typeName) const |
Given a resource's unique name, return whether or not this resource is or is derived from the resource described by the name. | |
virtual int | numberOfGenerationsFromBase (const std::string &typeName) const |
Given a resource's unique name, return the number of generations derived from the resource described from the name (or a negative value if this resource is not derived from the input resource type). | |
Unique Resource IDs | |
Because resources inherit PersistentObject, they (and the components they own) must provide unique identifiers. | |
const smtk::common::UUID & | id () const override |
Set/get the UUID of a resource. More... | |
bool | setId (const smtk::common::UUID &myID) override |
Set/get the UUID of a resource. More... | |
Resource Location | |
Resources must have a URL where they reside when not in memory. | |
const std::string & | location () const |
Set/get the location (a URL) where the resource is stored persistently. More... | |
virtual bool | setLocation (const std::string &location) |
Set/get the location (a URL) where the resource is stored persistently. More... | |
Naming | |
As they inherit PersistentObject, resources must provide a name. By default, if a resource has no name but has a location (URL), the stem of its filename is used as its name. | |
std::string | name () const override |
Set/get the user-assigned name of the resource. More... | |
virtual bool | setName (const std::string &name) |
Set/get the user-assigned name of the resource. More... | |
bool | isNameSet () const |
Set/get the user-assigned name of the resource. More... | |
Clean/Dirty State | |
Indicate whether the resource is in sync with the persistent storage at its location(). | |
virtual bool | clean () const |
Resources that have a non-empty location and are identical to the data stored at location are clean. More... | |
void | setClean (bool state=true) |
Resources that have a non-empty location and are identical to the data stored at location are clean. More... | |
Removing (un-managing) Resources | |
Resources are typically owned by an smtk::resource::Manager. However, operations may sometimes request that a resource be unmanaged (released from the manager and thus removed from memory). These methods provide information about the ownership of this resource. | |
void | setMarkedForRemoval (bool val) |
Mark the resource to indicate it is about to removed (meaning it is being removed from memory not necessarily for deletion) | |
virtual bool | isMarkedForRemoval () const |
Return whether the object is marked for removal. | |
ManagerPtr | manager () const |
Resources that are managed have a non-null pointer to their manager. | |
Finding, Visiting, and Filtering Components. | |
A resource owns a collection of components. These methods provide a consistent API for discovering, filtering, and iterating a resource's components. | |
virtual ComponentPtr | find (const smtk::common::UUID &compId) const =0 |
Given a resource component's UUID, return the resource component. | |
virtual Component * | component (const smtk::common::UUID &compId) const |
Given a component's UUID, return a raw pointer to the component. | |
template<typename ComponentType > | |
ComponentType * | componentAs (const smtk::common::UUID &uuid) const |
A templated version of component() that casts its result to a type. More... | |
virtual std::function< bool(const Component &)> | queryOperation (const std::string &) const |
given a std::string describing a query, return a functor for performing the query (accepts component as input, returns true if the component satisfies the query parameters). | |
virtual void | visit (std::function< void(const ComponentPtr &)> &v) const =0 |
visit all components in a resource. | |
ComponentSet | filter (const std::string &queryString) const |
Given a resource component's UUID, return the resource component. | |
template<typename Collection > | |
Collection | filterAs (const std::string &queryString) const |
given a a std::string describing a query and a type of container, return a set of components that satisfy both. More... | |
Cross-resource Links | |
Links provide a way to express relationships between components in other resources (as well as within the same resource). These methods provide access to the storage for link data. | |
Links & | links () override |
Fetch the links stored for this resource and its components. | |
const Links & | links () const override |
Fetch the links stored for this resource and its components. | |
Property Data | |
Resources and their components may be annotated with free-form properties. These methods provide read/write and read-only access to the annotations. | |
Properties & | properties () override |
const Properties & | properties () const override |
Resource Queries | |
Sometimes different types of resources (i.e., instances of different subclasses) may need a uniform API to provide information; query objects exist for this purpose and these methods provide read/write and read-only access to a query factory and cached data related to these queries. | |
const Queries & | queries () const |
Queries & | queries () |
Resource Locking | |
SMTK assumes that only one thread at a time may modify a resource and its components. Resources may be locked using the methods provided by the resource. Components may not be locked, so threads block access to the entire resource. Operations are designed to acquire resource locks for you before the operation is run. You should strive to use the operation framework for this rather than to manually lock resources. | |
Lock & | lock (Key()) const |
Classes that are granted permission to the key may retrieve the resource's lock. More... | |
LockType | locked () const |
Anyone can query whether or not the resource is locked. | |
Units and Dimensional Analysis. | |
Resources may own a "unit system" (i.e., a set of transformations that can be applied to convert dimensional measurements between scales in a consistent way) in order to accept user inputs in convenient units while ensuring SMTK's outputs are dimensionally consistent. Many resources may share reference to a common unit system, but this is not enforced; it is also possible for resources to have distinct unit systems. | |
virtual bool | setUnitsSystem (const shared_ptr< units::System > &unitsSystem) |
Sets the system of units used by this resource. | |
const shared_ptr< units::System > & | unitsSystem () const |
Gets the system of units used by this resource. | |
Resource Templates | |
A resource may have a template (also called a "schema," "theme," or "convention") describing a convention for how its contents are structured. Subclasses of the base resource class may override these methods to advertise their ability to model their structure according to multiple templates (by providing a valid template name and version). | |
virtual bool | setTemplateType (const smtk::string::Token &templateType) |
Set/get the "type" of a resource's template. More... | |
virtual smtk::string::Token | templateType () const |
Set/get the "type" of a resource's template. More... | |
virtual bool | setTemplateVersion (std::size_t templateVersion) |
Set/get the version number of the template this instance of the resource is based upon. More... | |
virtual std::size_t | templateVersion () const |
Set/get the "type" of a resource's template. More... | |
Copying and Updating | |
One resource may be used as a template for other resources. (This is also known as "prototypal inheritance.") Subclasses of the base resource class which implement these methods provide a way to clone, copy, and/or update resource templates/schemas. | |
virtual std::shared_ptr< Resource > | clone (CopyOptions &options) const |
Create an empty, un-managed clone of this resource instance. More... | |
virtual bool | copyInitialize (const std::shared_ptr< const Resource > &source, CopyOptions &options) |
Copy initial data from a source resource into this resource. More... | |
virtual bool | copyFinalize (const std::shared_ptr< const Resource > &source, CopyOptions &options) |
Finalize copying of a resource by resolving internal and external references among components copied from any of the source resources mapped in options. More... | |
void | copyUnitSystem (const std::shared_ptr< const Resource > &rsrc, const CopyOptions &options) |
Copy the units system from rsrc into this resource as specified by options. More... | |
void | copyProperties (const std::shared_ptr< const Resource > &rsrc, CopyOptions &options) |
Copy all property data from rsrc, mapping them along the way via options. More... | |
Public Member Functions inherited from smtk::resource::PersistentObject | |
smtkTypeMacroBase (smtk::resource::PersistentObject) | |
template<typename T > | |
T::Ptr | as () |
Attempt to cast this object to a subclass. | |
template<typename T > | |
T::ConstPtr | as () const |
Attempt to cast this object to a subclass. | |
Static Public Attributes | |
static const Resource::Index | type_index = std::type_index(typeid(Resource)).hash_code() |
static constexpr smtk::resource::Links::RoleType | VisuallyLinkedRole = -4 |
A role for components that implies their visibility in renderings should be linked to another object. More... | |
Protected Member Functions | |
Resource (const smtk::common::UUID &, ManagerPtr manager=nullptr) | |
Resource (ManagerPtr manager=nullptr) | |
bool | copyPropertiesForId (const std::shared_ptr< Resource > &rsrc, const smtk::common::UUID &sourceId, const smtk::common::UUID &targetId, const CopyOptions &options) |
Copy all property data for sourceId from rsrc into targetId of this resource. More... | |
void | copyLinks (const std::shared_ptr< const Resource > &rsrc, const CopyOptions &options) |
Copy links from rsrc (except those excluded by options), mapping them along the way. More... | |
Protected Attributes | |
WeakManagerPtr | m_manager |
std::shared_ptr< units::System > | m_unitsSystem |
Friends | |
class | Manager |
The Manager is a singleton interface for registering available plugins to manager instances. More... | |
template<typename Child , typename Parent > | |
class | DerivedFrom |
An abstract base class for SMTK resources.
Resources represent a collection of persistent objects written to a single file (i.e., a document). While it is possible – via resource::Links – for a document to reference objects external to a file, resources are intended mostly to be self-contained.
|
inlinevirtual |
Resources that have a non-empty location and are identical to the data stored at location are clean.
All other resources are dirty.
Operations that are write-operators (i.e., not read-only) should mark resources as modified. Saving a resource using its metadata's write method will mark the resource as clean. Loading a resource using its metadata's read method should return a clean resource.
Reimplemented in smtk::project::Project.
|
virtual |
Create an empty, un-managed clone of this resource instance.
Note that it is valid to (and the default implementation does) return a null pointer to indicate a resource cannot be cloned.
This method may be used create a resource for either copying (i.e., in order to create a new resource with the same structure as the original but with distinct UUIDs) or updating (i.e., in order to transform a resource from one revision of a template to another while preserving UUIDs).
This method does not copy the user-authored content of a resource. Use the copyInitialize() method on the returned clone if you wish to copy that data.
However, the options will determine whether ancillary data such as template-specific data, the unit system, and other information not related to the information being modeled by the resource is present in the returned clone.
Reimplemented in smtk::attribute::Resource.
|
inline |
A templated version of component()
that casts its result to a type.
This method performs a dynamic cast, so it may return nullptr even if there is a component with a matching uuid (in the case that it is of a different type than ComponentType).
|
virtual |
Finalize copying of a resource by resolving internal and external references among components copied from any of the source resources mapped in options.
After components are copied from the source, there may still be references to the original components; this method resolves those references to the copied components.
Reimplemented in smtk::attribute::Resource.
|
virtual |
Copy initial data from a source resource into this resource.
This method must be subclassed by resources that wish to support copying; the default implementation simply returns false.
Call this method on the result of clone() to copy persistent objects, properties, and other self-contained resource-specific data from the source into this resource.
If this method returns true, you should call copyFinalize() as well. If it returns false, you should abandon copying and allow the cloned resource to be destroyed.
This method begins the copy process by populating options.objectMapping(), which maps source- component UUIDs to pointers to components in this resource. You can (and should) call copyInitialize() on multiple resources before calling copyFinalize() on any of them; in this way, references between components of all the involved resources being copied can be properly resolved in the copyFinalize() method.
The copyFinalize() method adds any requested references between objects (both in the same and in external resources) using data stored in options by the copyInitialize() method. The two methods (copyInitialize() and copyFinalize()) allow duplication of multiple resources at once with references among them properly translated. This is accomplished by calling copyInitialize() on each resource to be processed and then calling copyFinalize() on each resource.
This method will always produce components that mirror the source components but have distinct UUIDs. On completion, the options object holds a map relating the source components to their copies in this resource.
Reimplemented in smtk::attribute::Resource.
|
protected |
Copy links from rsrc (except those excluded by options), mapping them along the way.
The objectMapping() in options is used to transform links, so that any UUID present in the mapping keys is transformed to the UUID of the map's corresponding value.
This method is intended for use by subclasses of Resource from within their copyFinalize() implementation.
void smtk::resource::Resource::copyProperties | ( | const std::shared_ptr< const Resource > & | rsrc, |
CopyOptions & | options | ||
) |
Copy all property data from rsrc, mapping them along the way via options.
This method is intended for use by subclasses of Resource from within their copyInitialize() implementation.
Note that this method must be called after components have been copied from rsrc as it relies upon options.objectMapping() to contain entries that map original component UUIDs to their new UUIDs.
If options.copyComponents() is false, any properties on the resource and non-component properties (property entries with a UUID that do not correspond to a component in rsrc) will still be copied.
|
protected |
Copy all property data for sourceId from rsrc into targetId of this resource.
This is called from copyProperties() for each entry in rsrc, possibly with the options objectMappings() applied.
This method returns true if any properties were copied and false otherwise.
Note that some properties may not be copy-constructible – these properties will not be copied and, depending on options, may result in a log message.
void smtk::resource::Resource::copyUnitSystem | ( | const std::shared_ptr< const Resource > & | rsrc, |
const CopyOptions & | options | ||
) |
Copy the units system from rsrc into this resource as specified by options.
This method is provided so subclasses that implement clone() do not need to repeat code common to all resources.
Collection smtk::resource::Resource::filterAs | ( | const std::string & | queryString | ) | const |
given a a std::string describing a query and a type of container, return a set of components that satisfy both.
Note that since this uses a dynamic pointer cast this can be slower than other find methods.
|
inlineoverridevirtual |
Set/get the UUID of a resource.
This may be modified at construction but should not change afterward unless there are exceptional circumstances.
Implements smtk::resource::PersistentObject.
|
inline |
Set/get the user-assigned name of the resource.
If no name has been assigned, return the stem of its filename. You may use isNameSet() to determine whether the returned name is generated or assigned.
|
inline |
Set/get the location (a URL) where the resource is stored persistently.
This may change when a user chooses to "Save As…" a different filename.
Classes that are granted permission to the key may retrieve the resource's lock.
This prevents other threads from modifying the resource simultaneously.
|
overridevirtual |
Set/get the user-assigned name of the resource.
If no name has been assigned, return the stem of its filename. You may use isNameSet() to determine whether the returned name is generated or assigned.
Reimplemented from smtk::resource::PersistentObject.
void smtk::resource::Resource::setClean | ( | bool | state = true | ) |
Resources that have a non-empty location and are identical to the data stored at location are clean.
All other resources are dirty.
Operations that are write-operators (i.e., not read-only) should mark resources as modified. Saving a resource using its metadata's write method will mark the resource as clean. Loading a resource using its metadata's read method should return a clean resource.
|
overridevirtual |
Set/get the UUID of a resource.
This may be modified at construction but should not change afterward unless there are exceptional circumstances.
Implements smtk::resource::PersistentObject.
|
virtual |
Set/get the location (a URL) where the resource is stored persistently.
This may change when a user chooses to "Save As…" a different filename.
|
virtual |
Set/get the user-assigned name of the resource.
If no name has been assigned, return the stem of its filename. You may use isNameSet() to determine whether the returned name is generated or assigned.
|
virtual |
Set/get the "type" of a resource's template.
A resource template-type is not required, but if present it can be used to register updaters for migrating from an old template to a newer version.
The default implementation returns an invalid string token (indicating the resource does not support templates). Subclasses must override this method if they wish to support document templates.
Reimplemented in smtk::attribute::Resource.
|
virtual |
Set/get the version number of the template this instance of the resource is based upon.
If non-zero, this number indicates the version number of the template (i.e., the attribute/item definitions for attribute resources) the current resource draws from. It is used during the update process to determine which updaters are applicable.
The default implementation always returns 0, indicating version numbers are not supported by resources of this type. Subclasses must override these methods if they wish to support document-template versioning.
Reimplemented in smtk::attribute::Resource.
|
virtual |
Set/get the "type" of a resource's template.
A resource template-type is not required, but if present it can be used to register updaters for migrating from an old template to a newer version.
The default implementation returns an invalid string token (indicating the resource does not support templates). Subclasses must override this method if they wish to support document templates.
Reimplemented in smtk::attribute::Resource.
|
virtual |
Set/get the "type" of a resource's template.
A resource template-type is not required, but if present it can be used to register updaters for migrating from an old template to a newer version.
The default implementation returns an invalid string token (indicating the resource does not support templates). Subclasses must override this method if they wish to support document templates.
Reimplemented in smtk::attribute::Resource.
|
friend |
The Manager is a singleton interface for registering available plugins to manager instances.
When a plugin is loaded, it creates a Client that adds itself to Manager's set of Client weak_ptrs. When a manager instance is passed into the Manager's "registerPluginsTo" method, each Client in the set that accepts a manager of this type constructs a Registry that tethers the scope of the manager's ability to use features from the plugin to the lifetime of the Registry object. Additionally, when a manager is passed into this class a register function is created that facilitates the registration of future plugins to the manager.
|
staticconstexpr |
A role for components that implies their visibility in renderings should be linked to another object.
When an object, A, without renderable geometry is linked to object(s), B, with renderable geometry, SMTK user-interface elements should show visibility-control badges for both A and B. This is indicated by a link from A to B.