An abstract base class for SMTK resources. More...

#include <Resource.h>

Inheritance diagram for smtk::resource::Resource:

Collaboration diagram for smtk::resource::Resource:

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 *	parentResource () const override
	Return a raw (not shared) pointer to the resource that owns this resource. More...

void	setParentResource (Resource *newParent)
	Sets the parent resource for this resource. More...

bool	setManager (ManagerPtr newManager)
	Set the manager that the resource will use to decode its link information. More...

	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...

std::string	absoluteLocation (bool createDir=false) const
	As a convenience, fetch the absolute path to a resource from its location. 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	setUnitSystem (const shared_ptr< units::System > &unitSystem)
	Sets the system of units used by this resource.

virtual bool	setUnitsSystem (const shared_ptr< units::System > &unitsSystem)
	Sets the system of units used by this resource.

const shared_ptr< units::System > &	unitSystem () const
	Gets the system of units used by this resource.

const shared_ptr< units::System > &	unitsSystem () const
	Sets 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 Member Functions
static constexpr smtk::resource::Links::RoleType	visuallyLinkedRole ()

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_unitSystem

Friends
class	Manager
	The Manager is a singleton interface for registering available plugins to manager instances. More...

template<typename Child , typename Parent >
class	DerivedFrom

Detailed Description

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.

Member Function Documentation

◆ absoluteLocation()

std::string smtk::resource::Resource::absoluteLocation ( bool createDir = false ) const

As a convenience, fetch the absolute path to a resource from its location.

For URLs with a protocol (e.g., "https://foo.com/resource.smtk") or local paths with a leading slash (e.g., "/foo/resource.smtk"), this is exactly the resource's location() string.

However, if a resource has a relative path, we must look to see whether it has a parent resource; if so, this method is recursively called on the parent to find its absolute path so that the relative path of the child resource can be determined.

When a resource (the immediate one or any parent) has a relative location but no parent, then the current working directory is used to determine its absolute path.

As an added convenience, you may pass "true" as a second argument to this method to have it create the containing directory of the resource's location for you. This is for use by Write operations.

See also: smtk::common::Paths::isRelative, smtk::common::Paths::currentDirectory

◆ clean()

virtual bool smtk::resource::Resource::clean ( ) const

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.

◆ clone()

std::shared_ptr< Resource > smtk::resource::Resource::clone ( CopyOptions & options ) const

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.

◆ componentAs()

template<typename ComponentType >

ComponentType* smtk::resource::Resource::componentAs ( const smtk::common::UUID & uuid ) const

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

◆ copyFinalize()

bool smtk::resource::Resource::copyFinalize	(	const std::shared_ptr< const Resource > &	source,
		CopyOptions &	options
	)

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.

◆ copyInitialize()

bool smtk::resource::Resource::copyInitialize	(	const std::shared_ptr< const Resource > &	source,
		CopyOptions &	options
	)

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.

◆ copyLinks()

void smtk::resource::Resource::copyLinks	(	const std::shared_ptr< const Resource > &	rsrc,
		const CopyOptions &	options
	)

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.

◆ copyProperties()

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.

◆ copyPropertiesForId()

bool smtk::resource::Resource::copyPropertiesForId	(	const std::shared_ptr< Resource > &	rsrc,
		const smtk::common::UUID &	sourceId,
		const smtk::common::UUID &	targetId,
		const CopyOptions &	options
	)

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.

◆ copyUnitSystem()

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.

◆ filterAs()

template<typename Collection >

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.

◆ id()

const smtk::common::UUID& smtk::resource::Resource::id ( ) const

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.

◆ isNameSet()

bool smtk::resource::Resource::isNameSet ( ) const

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.

◆ location()

const std::string& smtk::resource::Resource::location ( ) const

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.

◆ lock()

Lock& smtk::resource::Resource::lock ( Key() ) const

inline

Classes that are granted permission to the key may retrieve the resource's lock.

This prevents other threads from modifying the resource simultaneously.

◆ name()

std::string smtk::resource::Resource::name ( ) const

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.

◆ parentResource()

Resource* smtk::resource::Resource::parentResource ( ) const

inlineoverridevirtual

Return a raw (not shared) pointer to the resource that owns this resource.

Note that not all resources will have an owning resource.

Implements smtk::resource::PersistentObject.

◆ setClean()

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.

◆ setId()

bool smtk::resource::Resource::setId ( const smtk::common::UUID & myID )

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.

◆ setLocation()

bool smtk::resource::Resource::setLocation ( const std::string & location )

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.

◆ setManager()

bool smtk::resource::Resource::setManager ( ManagerPtr newManager )

Set the manager that the resource will use to decode its link information.

Note: this is typically the same as the manager that is managing the resource but is not the case when dealing with resources that are not being managed.

◆ setName()

bool smtk::resource::Resource::setName ( const std::string & name )

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.

◆ setParentResource()

void smtk::resource::Resource::setParentResource ( Resource * newParent )

inline

Sets the parent resource for this resource.

Note that newParent can be null which means the resource is no longer owned by another.

◆ setTemplateType()

bool smtk::resource::Resource::setTemplateType ( const smtk::string::Token & templateType )

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.

◆ setTemplateVersion()

bool smtk::resource::Resource::setTemplateVersion ( std::size_t templateVersion )

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.

◆ templateType()

smtk::string::Token smtk::resource::Resource::templateType ( ) const

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.

◆ templateVersion()

std::size_t smtk::resource::Resource::templateVersion ( ) const

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.

Friends And Related Function Documentation

◆ Manager

friend class Manager

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.

Member Data Documentation

◆ VisuallyLinkedRole

constexpr smtk::resource::Links::RoleType smtk::resource::Resource::VisuallyLinkedRole = -4

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.

The documentation for this class was generated from the following files:

/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/resource/Resource.h
/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/resource/Resource.cxx

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Function Documentation

◆ absoluteLocation()

◆ clean()

◆ clone()

◆ componentAs()

◆ copyFinalize()

◆ copyInitialize()

◆ copyLinks()

◆ copyProperties()

◆ copyPropertiesForId()

◆ copyUnitSystem()

◆ filterAs()

◆ id()

◆ isNameSet()

◆ location()

◆ lock()

◆ name()

◆ parentResource()

◆ setClean()

◆ setId()

◆ setLocation()

◆ setManager()

◆ setName()

◆ setParentResource()

◆ setTemplateType()

◆ setTemplateVersion()

◆ templateType()

◆ templateVersion()

Friends And Related Function Documentation

◆ Manager

Member Data Documentation

◆ VisuallyLinkedRole