All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ArResolver Class Referenceabstract

Interface for the asset resolution system. More...

+ Inheritance diagram for ArResolver:

Public Member Functions

 ArResolver (const ArResolver &)=delete
 
ArResolveroperator= (const ArResolver &)=delete
 
Path Resolution Operations

virtual AR_API void ConfigureResolverForAsset (const std::string &path)=0
 Configures the resolver for a given asset path. More...
 
virtual AR_API std::string AnchorRelativePath (const std::string &anchorPath, const std::string &path)=0
 Returns the path formed by anchoring path to anchorPath. More...
 
virtual AR_API bool IsRelativePath (const std::string &path)=0
 Returns true if the given path is a relative path. More...
 
virtual AR_API bool IsRepositoryPath (const std::string &path)=0
 Returns true if the given path is a repository path. More...
 
virtual AR_API bool IsSearchPath (const std::string &path)=0
 Returns whether this path is a search path. More...
 
virtual AR_API std::string GetExtension (const std::string &path)=0
 Returns the normalized extension for the given path. More...
 
virtual AR_API std::string ComputeNormalizedPath (const std::string &path)=0
 Returns a normalized version of the given path. More...
 
virtual AR_API std::string ComputeRepositoryPath (const std::string &path)=0
 Returns the computed repository path using the current resolver. More...
 
virtual AR_API std::string ComputeLocalPath (const std::string &path)=0
 Returns the local path for the given path. More...
 
virtual AR_API std::string Resolve (const std::string &path)=0
 Returns the resolved filesystem path for the file identified by the given path if it exists. More...
 
Asset Resolver Context Operations

virtual AR_API void BindContext (const ArResolverContext &context, VtValue *bindingData)=0
 Binds the given context to this resolver. More...
 
virtual AR_API void UnbindContext (const ArResolverContext &context, VtValue *bindingData)=0
 Unbind the given context from this resolver. More...
 
virtual AR_API ArResolverContext CreateDefaultContext ()=0
 Return a default ArResolverContext that may be bound to this resolver to resolve assets when no other context is explicitly specified. More...
 
virtual AR_API ArResolverContext CreateDefaultContextForAsset (const std::string &filePath)=0
 Return a default ArResolverContext that may be bound to this resolver to resolve the asset located at filePath when no other context is explicitly specified. More...
 
virtual AR_API void RefreshContext (const ArResolverContext &context)=0
 Refresh any caches associated with the given context. More...
 
virtual AR_API ArResolverContext GetCurrentContext ()=0
 Returns the currently-bound asset resolver context. More...
 
File/asset-specific Operations

virtual AR_API std::string ResolveWithAssetInfo (const std::string &path, ArAssetInfo *assetInfo)=0
 Returns the resolved filesystem path for the file identified by path following the same path resolution behavior as in Resolve(const std::string&). More...
 
virtual AR_API void UpdateAssetInfo (const std::string &identifier, const std::string &filePath, const std::string &fileVersion, ArAssetInfo *assetInfo)=0
 Update assetInfo with respect to the given fileVersion . More...
 
virtual AR_API VtValue GetModificationTimestamp (const std::string &path, const std::string &resolvedPath)=0
 Returns a value representing the last time the asset identified by path was modified. More...
 
virtual AR_API bool FetchToLocalResolvedPath (const std::string &path, const std::string &resolvedPath)=0
 Fetch the asset identified by path to the filesystem location specified by resolvedPath. More...
 
virtual AR_API std::shared_ptr
< ArAsset
OpenAsset (const std::string &resolvedPath)=0
 Returns an ArAsset object for the asset located at resolvedPath. More...
 
virtual AR_API bool CanWriteLayerToPath (const std::string &path, std::string *whyNot)=0
 Returns true if a file may be written to the given path, false otherwise. More...
 
virtual AR_API bool CanCreateNewLayerWithIdentifier (const std::string &identifier, std::string *whyNot)=0
 Returns true if a new file may be created using the given identifier, false otherwise. More...
 
Scoped Resolution Cache

A scoped resolution cache indicates to the resolver that results of calls to Resolve should be cached for a certain scope. This is important for performance and also for consistency – it ensures that repeated calls to Resolve with the same parameters will return the same result.

A resolution cache scope is opened by a call to BeginCacheScope and must be closed with a matching call to EndCacheScope. The resolver must cache the results of Resolve until the scope is closed. Note that these calls may be nested.

Cache scopes are thread-specific: if multiple threads are running and a cache scope is opened in one of those threads, caching should be enabled in that thread only.

When opening a scope, a resolver may return additional data for implementation-specific purposes. This data may be shared across threads, so long as it is safe to access this data concurrently.

ArResolverScopedCache is an RAII object for managing cache scope lifetimes and data. Clients should generally use that class rather than calling the BeginCacheScope and EndCacheScope functions manually.

See Also
ArResolverScopedCache
virtual AR_API void BeginCacheScope (VtValue *cacheScopeData)=0
 Mark the start of a resolution caching scope. More...
 
virtual AR_API void EndCacheScope (VtValue *cacheScopeData)=0
 Mark the end of a resolution caching scope. More...
 

Detailed Description

Interface for the asset resolution system.

An asset resolver is responsible for resolving asset information (including the asset's physical path) from a logical path.

See Implementing a Custom Resolver for information on how to customize asset resolution behavior by implementing a subclass of ArResolver. Clients may use ArGetResolver to access the configured asset resolver.

Definition at line 53 of file resolver.h.

Member Function Documentation

virtual AR_API std::string AnchorRelativePath ( const std::string &  anchorPath,
const std::string &  path 
)
pure virtual

Returns the path formed by anchoring path to anchorPath.

If anchorPath ends with a trailing '/', it is treated as a directory to which path will be anchored. Otherwise, it is treated as a file and path will be anchored to its containing directory.

If anchorPath is empty, path will be returned as-is.

If path is empty or not a relative path, it will be returned as-is.

Implemented in ArDefaultResolver.

virtual AR_API void BeginCacheScope ( VtValue cacheScopeData)
pure virtual

Mark the start of a resolution caching scope.

Clients should generally use ArResolverScopedCache instead of calling this function directly.

Resolvers may fill cacheScopeData with arbitrary data. Clients may also pass in a cacheScopeData populated by an earlier call to BeginCacheScope to allow the resolver access to that information.

See Also
ArResolverScopedCache

Implemented in ArDefaultResolver.

virtual AR_API void BindContext ( const ArResolverContext context,
VtValue bindingData 
)
pure virtual

Binds the given context to this resolver.

Clients should generally use ArResolverContextBinder instead of calling this function directly.

See Also
ArResolverContextBinder

Implemented in ArDefaultResolver.

virtual AR_API bool CanCreateNewLayerWithIdentifier ( const std::string &  identifier,
std::string *  whyNot 
)
pure virtual

Returns true if a new file may be created using the given identifier, false otherwise.

If this function returns false and whyNot is not nullptr, it will be filled in with an explanation.

Implemented in ArDefaultResolver.

virtual AR_API bool CanWriteLayerToPath ( const std::string &  path,
std::string *  whyNot 
)
pure virtual

Returns true if a file may be written to the given path, false otherwise.

If this function returns false and whyNot is not nullptr, it will be filled in with an explanation.

Implemented in ArDefaultResolver.

virtual AR_API std::string ComputeLocalPath ( const std::string &  path)
pure virtual

Returns the local path for the given path.

Implemented in ArDefaultResolver.

virtual AR_API std::string ComputeNormalizedPath ( const std::string &  path)
pure virtual

Returns a normalized version of the given path.

Implemented in ArDefaultResolver.

virtual AR_API std::string ComputeRepositoryPath ( const std::string &  path)
pure virtual

Returns the computed repository path using the current resolver.

Implemented in ArDefaultResolver.

virtual AR_API void ConfigureResolverForAsset ( const std::string &  path)
pure virtual

Configures the resolver for a given asset path.

Implemented in ArDefaultResolver.

virtual AR_API ArResolverContext CreateDefaultContext ( )
pure virtual

Return a default ArResolverContext that may be bound to this resolver to resolve assets when no other context is explicitly specified.

This function should not automatically bind this context, but should create one that may be used later.

Implemented in ArDefaultResolver.

virtual AR_API ArResolverContext CreateDefaultContextForAsset ( const std::string &  filePath)
pure virtual

Return a default ArResolverContext that may be bound to this resolver to resolve the asset located at filePath when no other context is explicitly specified.

This function should not automatically bind this context, but should create one that may be used later.

Implemented in ArDefaultResolver.

virtual AR_API void EndCacheScope ( VtValue cacheScopeData)
pure virtual

Mark the end of a resolution caching scope.

Clients should generally use ArResolverScopedCache instead of calling this function directly.

cacheScopeData should contain the data that was populated by the previous corresponding call to BeginCacheScope.

See Also
ArResolverScopedCache

Implemented in ArDefaultResolver.

virtual AR_API bool FetchToLocalResolvedPath ( const std::string &  path,
const std::string &  resolvedPath 
)
pure virtual

Fetch the asset identified by path to the filesystem location specified by resolvedPath.

resolvedPath is the resolved path that results from calling Resolve or ResolveWithAssetInfo on path.

This method provides a way for consumers that expect assets to exist as physical files on disk to retrieve data from systems that store data in external data stores, e.g. databases, etc.

Returns true if the asset was successfully fetched to the specified resolvedPath or if no fetching was required. If resolvedPath is not a local path or the asset could not be fetched to that path, returns false.

Implemented in ArDefaultResolver.

virtual AR_API ArResolverContext GetCurrentContext ( )
pure virtual

Returns the currently-bound asset resolver context.

See Also
ArResolver::BindContext, ArResolver::UnbindContext

Implemented in ArDefaultResolver.

virtual AR_API std::string GetExtension ( const std::string &  path)
pure virtual

Returns the normalized extension for the given path.

Implemented in ArDefaultResolver.

virtual AR_API VtValue GetModificationTimestamp ( const std::string &  path,
const std::string &  resolvedPath 
)
pure virtual

Returns a value representing the last time the asset identified by path was modified.

resolvedPath is the resolved path of the asset.

Implementations may use whatever value is most appropriate for this timestamp. The value must be equality comparable, and this function must return a different timestamp whenever an asset has been modified. For instance, if an asset is stored as a file on disk, the timestamp may simply be that file's mtime.

If a timestamp cannot be retrieved, returns an empty VtValue.

Implemented in ArDefaultResolver.

virtual AR_API bool IsRelativePath ( const std::string &  path)
pure virtual

Returns true if the given path is a relative path.

Implemented in ArDefaultResolver.

virtual AR_API bool IsRepositoryPath ( const std::string &  path)
pure virtual

Returns true if the given path is a repository path.

Implemented in ArDefaultResolver.

virtual AR_API bool IsSearchPath ( const std::string &  path)
pure virtual

Returns whether this path is a search path.

Implemented in ArDefaultResolver.

virtual AR_API std::shared_ptr<ArAsset> OpenAsset ( const std::string &  resolvedPath)
pure virtual

Returns an ArAsset object for the asset located at resolvedPath.

Returns an invalid std::shared_ptr if object could not be created.

The returned ArAsset object provides functions for accessing the contents of the specified asset.

Note that clients may still be using the data associated with this object even after the last shared_ptr has been destroyed. For example, a client may have created a memory mapping using the FILE* presented in the ArAsset object; this would preclude truncating or overwriting any of the contents of that file.

Implemented in ArDefaultResolver.

virtual AR_API void RefreshContext ( const ArResolverContext context)
pure virtual

Refresh any caches associated with the given context.

Implemented in ArDefaultResolver.

virtual AR_API std::string Resolve ( const std::string &  path)
pure virtual

Returns the resolved filesystem path for the file identified by the given path if it exists.

If the file does not exist, returns an empty string.

Implemented in ArDefaultResolver.

virtual AR_API std::string ResolveWithAssetInfo ( const std::string &  path,
ArAssetInfo assetInfo 
)
pure virtual

Returns the resolved filesystem path for the file identified by path following the same path resolution behavior as in Resolve(const std::string&).

If the file identified by path represents an asset and assetInfo is not nullptr, the resolver should populate assetInfo with whatever additional metadata it knows or can reasonably compute about the asset without actually opening it.

See Also
Resolve(const std::string&).

Implemented in ArDefaultResolver.

virtual AR_API void UnbindContext ( const ArResolverContext context,
VtValue bindingData 
)
pure virtual

Unbind the given context from this resolver.

Clients should generally use ArResolverContextBinder instead of calling this function directly.

See Also
ArResolverContextBinder

Implemented in ArDefaultResolver.

virtual AR_API void UpdateAssetInfo ( const std::string &  identifier,
const std::string &  filePath,
const std::string &  fileVersion,
ArAssetInfo assetInfo 
)
pure virtual

Update assetInfo with respect to the given fileVersion .

Note
This API is currently in flux. In general, you should prefer to call ResolveWithAssetInfo()

Implemented in ArDefaultResolver.


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