HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
resolver.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_AR_RESOLVER_H
25 #define PXR_USD_AR_RESOLVER_H
26 
27 /// \file ar/resolver.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/ar/api.h"
31 #include <memory>
32 #include <string>
33 #include <vector>
34 
36 
37 class ArAsset;
38 class ArAssetInfo;
39 class ArResolverContext;
40 class TfType;
41 class VtValue;
42 
43 /// \class ArResolver
44 ///
45 /// Interface for the asset resolution system. An asset resolver is
46 /// responsible for resolving asset information (including the asset's
47 /// physical path) from a logical path.
48 ///
49 /// See \ref ar_implementing_resolver for information on how to customize
50 /// asset resolution behavior by implementing a subclass of ArResolver.
51 /// Clients may use #ArGetResolver to access the configured asset resolver.
52 ///
53 class ArResolver
54 {
55 public:
56  AR_API
57  virtual ~ArResolver();
58 
59  // Disallow copies
60  ArResolver(const ArResolver&) = delete;
61  ArResolver& operator=(const ArResolver&) = delete;
62 
63  // --------------------------------------------------------------------- //
64  /// \anchor ArResolver_resolution
65  /// \name Path Resolution Operations
66  ///
67  /// @{
68  // --------------------------------------------------------------------- //
69 
70  /// Configures the resolver for a given asset path
71  AR_API
72  virtual void ConfigureResolverForAsset(const std::string& path) = 0;
73 
74  /// Returns the path formed by anchoring \p path to \p anchorPath.
75  ///
76  /// If \p anchorPath ends with a trailing '/', it is treated as
77  /// a directory to which \p path will be anchored. Otherwise, it
78  /// is treated as a file and \p path will be anchored to its
79  /// containing directory.
80  ///
81  /// If \p anchorPath is empty, \p path will be returned as-is.
82  ///
83  /// If \p path is empty or not a relative path, it will be
84  /// returned as-is.
85  AR_API
87  const std::string& anchorPath,
88  const std::string& path) = 0;
89 
90  /// Returns true if the given path is a relative path.
91  AR_API
92  virtual bool IsRelativePath(const std::string& path) = 0;
93 
94  /// Returns true if the given path is a repository path.
95  AR_API
96  virtual bool IsRepositoryPath(const std::string& path) = 0;
97 
98  /// Returns whether this path is a search path.
99  AR_API
100  virtual bool IsSearchPath(const std::string& path) = 0;
101 
102  /// Returns the normalized extension for the given \p path.
103  AR_API
104  virtual std::string GetExtension(const std::string& path) = 0;
105 
106  /// Returns a normalized version of the given \p path
107  AR_API
108  virtual std::string ComputeNormalizedPath(const std::string& path) = 0;
109 
110  /// Returns the computed repository path using the current resolver
111  AR_API
112  virtual std::string ComputeRepositoryPath(const std::string& path) = 0;
113 
114  /// Returns the local path for the given \p path.
115  AR_API
116  virtual std::string ComputeLocalPath(const std::string& path) = 0;
117 
118  /// Returns the resolved filesystem path for the file identified by
119  /// the given \p path if it exists. If the file does not exist,
120  /// returns an empty string.
121  AR_API
122  virtual std::string Resolve(const std::string& path) = 0;
123 
124  /// @}
125 
126  // --------------------------------------------------------------------- //
127  /// \anchor ArResolver_context
128  /// \name Asset Resolver Context Operations
129  ///
130  /// @{
131  // --------------------------------------------------------------------- //
132 
133  /// Binds the given context to this resolver.
134  ///
135  /// Clients should generally use ArResolverContextBinder instead of calling
136  /// this function directly.
137  ///
138  /// \see ArResolverContextBinder
139  AR_API
140  virtual void BindContext(
141  const ArResolverContext& context,
142  VtValue* bindingData) = 0;
143 
144  /// Unbind the given context from this resolver.
145  ///
146  /// Clients should generally use ArResolverContextBinder instead of calling
147  /// this function directly.
148  ///
149  /// \see ArResolverContextBinder
150  AR_API
151  virtual void UnbindContext(
152  const ArResolverContext& context,
153  VtValue* bindingData) = 0;
154 
155  /// Return a default ArResolverContext that may be bound to this resolver
156  /// to resolve assets when no other context is explicitly specified.
157  ///
158  /// This function should not automatically bind this context, but should
159  /// create one that may be used later.
160  AR_API
162 
163  /// Return a default ArResolverContext that may be bound to this resolver
164  /// to resolve the asset located at \p filePath when no other context is
165  /// explicitly specified.
166  ///
167  /// This function should not automatically bind this context, but should
168  /// create one that may be used later.
169  AR_API
171  const std::string& filePath) = 0;
172 
173  /// Refresh any caches associated with the given context.
174  AR_API
175  virtual void RefreshContext(const ArResolverContext& context) = 0;
176 
177  /// Returns the currently-bound asset resolver context.
178  ///
179  /// \see ArResolver::BindContext, ArResolver::UnbindContext
180  AR_API
181  virtual ArResolverContext GetCurrentContext() = 0;
182 
183  /// @}
184 
185  // --------------------------------------------------------------------- //
186  /// \anchor ArResolver_files
187  /// \name File/asset-specific Operations
188  ///
189  /// @{
190  // --------------------------------------------------------------------- //
191 
192  /// Returns the resolved filesystem path for the file identified
193  /// by \p path following the same path resolution behavior as in
194  /// \ref Resolve(const std::string&).
195  ///
196  /// If the file identified by \p path represents an asset and
197  /// \p assetInfo is not \c nullptr, the resolver should populate
198  /// \p assetInfo with whatever additional metadata it knows or can
199  /// reasonably compute about the asset without actually opening it.
200  ///
201  /// \see Resolve(const std::string&).
202  AR_API
204  const std::string& path,
205  ArAssetInfo* assetInfo) = 0;
206 
207  /// Update \p assetInfo with respect to the given \p fileVersion .
208  /// \note This API is currently in flux. In general, you should prefer
209  /// to call ResolveWithAssetInfo()
210  AR_API
211  virtual void UpdateAssetInfo(
212  const std::string& identifier,
213  const std::string& filePath,
214  const std::string& fileVersion,
215  ArAssetInfo* assetInfo) = 0;
216 
217  /// Returns a value representing the last time the asset identified
218  /// by \p path was modified. \p resolvedPath is the resolved path
219  /// of the asset.
220  ///
221  /// Implementations may use whatever value is most appropriate
222  /// for this timestamp. The value must be equality comparable,
223  /// and this function must return a different timestamp whenever
224  /// an asset has been modified. For instance, if an asset is stored
225  /// as a file on disk, the timestamp may simply be that file's mtime.
226  ///
227  /// If a timestamp cannot be retrieved, returns an empty VtValue.
228  AR_API
230  const std::string& path,
231  const std::string& resolvedPath) = 0;
232 
233  /// Fetch the asset identified by \p path to the filesystem location
234  /// specified by \p resolvedPath. \p resolvedPath is the resolved path
235  /// that results from calling Resolve or ResolveWithAssetInfo on
236  /// \p path.
237  ///
238  /// This method provides a way for consumers that expect assets
239  /// to exist as physical files on disk to retrieve data from
240  /// systems that store data in external data stores, e.g. databases,
241  /// etc.
242  ///
243  /// Returns true if the asset was successfully fetched to the specified
244  /// \p resolvedPath or if no fetching was required. If \p resolvedPath
245  /// is not a local path or the asset could not be fetched to that path,
246  /// returns false.
247  AR_API
248  virtual bool FetchToLocalResolvedPath(
249  const std::string& path,
250  const std::string& resolvedPath) = 0;
251 
252  /// Returns an ArAsset object for the asset located at \p resolvedPath.
253  /// Returns an invalid std::shared_ptr if object could not be created.
254  ///
255  /// The returned ArAsset object provides functions for accessing the
256  /// contents of the specified asset.
257  ///
258  /// Note that clients may still be using the data associated with
259  /// this object even after the last shared_ptr has been destroyed. For
260  /// example, a client may have created a memory mapping using the FILE*
261  /// presented in the ArAsset object; this would preclude truncating or
262  /// overwriting any of the contents of that file.
263  AR_API
264  virtual std::shared_ptr<ArAsset> OpenAsset(
265  const std::string& resolvedPath) = 0;
266 
267  /// Create path needed to write a file to the given \p path.
268  ///
269  /// For example:
270  /// - A filesystem-based resolver might create the directories specified
271  /// in \p path.
272  /// - A database-based resolver might create a new table, or it might
273  /// ignore this altogether.
274  ///
275  /// In practice, when writing a layer, CanWriteLayerToPath will be called
276  /// first to check if writing is permitted. If this returns true, then
277  /// CreatePathForLayer will be called before writing the layer out.
278  ///
279  /// Returns true on success, false otherwise.
280  AR_API
281  virtual bool CreatePathForLayer(
282  const std::string& path) = 0;
283 
284  /// Returns true if a file may be written to the given \p path, false
285  /// otherwise.
286  ///
287  /// In practice, when writing a layer, CanWriteLayerToPath will be called
288  /// first to check if writing is permitted. If this returns true, then
289  /// CreatePathForLayer will be called before writing the layer out.
290  ///
291  /// If this function returns false and \p whyNot is not \c nullptr,
292  /// it will be filled in with an explanation.
293  AR_API
294  virtual bool CanWriteLayerToPath(
295  const std::string& path,
296  std::string* whyNot) = 0;
297 
298  /// Returns true if a new file may be created using the given
299  /// \p identifier, false otherwise.
300  ///
301  /// If this function returns false and \p whyNot is not \c nullptr,
302  /// it will be filled in with an explanation.
303  AR_API
304  virtual bool CanCreateNewLayerWithIdentifier(
305  const std::string& identifier,
306  std::string* whyNot) = 0;
307 
308  /// @}
309 
310  // --------------------------------------------------------------------- //
311  /// \anchor ArResolver_scopedCache
312  /// \name Scoped Resolution Cache
313  ///
314  /// A scoped resolution cache indicates to the resolver that results of
315  /// calls to Resolve should be cached for a certain scope. This is
316  /// important for performance and also for consistency -- it ensures
317  /// that repeated calls to Resolve with the same parameters will
318  /// return the same result.
319  ///
320  /// A resolution cache scope is opened by a call to BeginCacheScope and
321  /// must be closed with a matching call to EndCacheScope. The resolver must
322  /// cache the results of Resolve until the scope is closed. Note that these
323  /// calls may be nested.
324  ///
325  /// Cache scopes are thread-specific: if multiple threads are running and
326  /// a cache scope is opened in one of those threads, caching should be
327  /// enabled in that thread only.
328  ///
329  /// When opening a scope, a resolver may return additional data for
330  /// implementation-specific purposes. This data may be shared across
331  /// threads, so long as it is safe to access this data concurrently.
332  ///
333  /// ArResolverScopedCache is an RAII object for managing cache scope
334  /// lifetimes and data. Clients should generally use that class rather
335  /// than calling the BeginCacheScope and EndCacheScope functions manually.
336  ///
337  /// \see ArResolverScopedCache
338  /// @{
339  // --------------------------------------------------------------------- //
340 
341  /// Mark the start of a resolution caching scope.
342  ///
343  /// Clients should generally use ArResolverScopedCache instead of calling
344  /// this function directly.
345  ///
346  /// Resolvers may fill \p cacheScopeData with arbitrary data. Clients may
347  /// also pass in a \p cacheScopeData populated by an earlier call to
348  /// BeginCacheScope to allow the resolver access to that information.
349  ///
350  /// \see ArResolverScopedCache
351  AR_API
352  virtual void BeginCacheScope(
353  VtValue* cacheScopeData) = 0;
354 
355  /// Mark the end of a resolution caching scope.
356  ///
357  /// Clients should generally use ArResolverScopedCache instead of calling
358  /// this function directly.
359  ///
360  /// \p cacheScopeData should contain the data that was populated by the
361  /// previous corresponding call to BeginCacheScope.
362  ///
363  /// \see ArResolverScopedCache
364  AR_API
365  virtual void EndCacheScope(
366  VtValue* cacheScopeData) = 0;
367 
368  /// @}
369 
370 protected:
371  AR_API
372  ArResolver();
373 };
374 
375 /// Returns the configured asset resolver.
376 ///
377 /// When first called, this function will determine the ArResolver subclass
378 /// to use for asset resolution via the following process:
379 ///
380 /// - If a preferred resolver has been set via \ref ArSetPreferredResolver,
381 /// it will be selected.
382 ///
383 /// - Otherwise, a list of available ArResolver subclasses in plugins will
384 /// be generated. If multiple ArResolver subclasses are found, the list
385 /// will be sorted by typename. ArDefaultResolver will be added as the last
386 /// element of this list, and the first resolver in the list will be
387 /// selected.
388 ///
389 /// - The plugin for the selected subclass will be loaded and an instance
390 /// of the subclass will be constructed.
391 ///
392 /// - If an error occurs, an ArDefaultResolver will be constructed.
393 ///
394 /// The constructed ArResolver subclass will be cached and used to service
395 /// function calls made on the returned resolver.
396 ///
397 /// Note that this function may not return the constructed subclass itself,
398 /// meaning that dynamic casts to the subclass type may fail. See
399 /// ArGetUnderlyingResolver if access to this object is needed.
400 AR_API
402 
403 /// Set the preferred ArResolver subclass used by ArGetResolver.
404 ///
405 /// Consumers may override ArGetResolver's plugin resolver discovery and
406 /// force the use of a specific resolver subclass by calling this
407 /// function with the typename of the implementation to use.
408 ///
409 /// If the subclass specified by \p resolverTypeName cannot be found,
410 /// ArGetResolver will issue a warning and fall back to using
411 /// ArDefaultResolver.
412 ///
413 /// This must be called before the first call to ArGetResolver.
414 AR_API
415 void ArSetPreferredResolver(const std::string& resolverTypeName);
416 
417 /// \name Advanced API
418 ///
419 /// \warning These functions should typically not be used by consumers except
420 /// in very specific cases. Consumers who want to retrieve an ArResolver to
421 /// perform asset resolution should use \ref ArGetResolver.
422 ///
423 /// @{
424 
425 /// Returns the underlying ArResolver instance used by ArGetResolver.
426 ///
427 /// This function returns the instance of the ArResolver subclass used by
428 /// ArGetResolver and can be dynamic_cast to that type.
429 ///
430 /// \warning This functions should typically not be used by consumers except
431 /// in very specific cases. Consumers who want to retrieve an ArResolver to
432 /// perform asset resolution should use \ref ArGetResolver.
433 AR_API
435 
436 /// Returns list of TfTypes for available ArResolver subclasses.
437 ///
438 /// This function returns the list of ArResolver subclasses used to determine
439 /// the resolver implementation returned by \ref ArGetResolver. See
440 /// documentation on that function for more details.
441 ///
442 /// If this function is called from within a call (or calls) to
443 /// \ref ArCreateResolver, the ArResolver subclass(es) being created will
444 /// be removed from the returned list.
445 ///
446 /// This function is not safe to call concurrently with itself or
447 /// \ref ArCreateResolver.
448 ///
449 /// \warning This functions should typically not be used by consumers except
450 /// in very specific cases. Consumers who want to retrieve an ArResolver to
451 /// perform asset resolution should use \ref ArGetResolver.
452 AR_API
453 std::vector<TfType> ArGetAvailableResolvers();
454 
455 /// Construct an instance of the ArResolver subclass specified by
456 /// \p resolverType.
457 ///
458 /// This function will load the plugin for the given \p resolverType and
459 /// construct and return a new instance of the specified ArResolver subclass.
460 /// If an error occurs, coding errors will be emitted and this function
461 /// will return an ArDefaultResolver instance.
462 ///
463 /// Note that this function *does not* change the resolver used by
464 /// \ref ArGetResolver to an instance of \p resolverType.
465 ///
466 /// This function is not safe to call concurrently with itself or
467 /// \ref ArGetAvailableResolvers.
468 ///
469 /// \warning This functions should typically not be used by consumers except
470 /// in very specific cases. Consumers who want to retrieve an ArResolver to
471 /// perform asset resolution should use \ref ArGetResolver.
472 AR_API
473 std::unique_ptr<ArResolver> ArCreateResolver(const TfType& resolverType);
474 
475 /// @}
476 
478 
479 #endif // PXR_USD_AR_RESOLVER_H
AR_API std::unique_ptr< ArResolver > ArCreateResolver(const TfType &resolverType)
virtual AR_API void RefreshContext(const ArResolverContext &context)=0
Refresh any caches associated with the given context.
virtual AR_API std::string ComputeLocalPath(const std::string &path)=0
Returns the local path for the given path.
virtual AR_API ArResolverContext CreateDefaultContextForAsset(const std::string &filePath)=0
Definition: asset.h:43
#define AR_API
Definition: api.h:40
virtual AR_API VtValue GetModificationTimestamp(const std::string &path, const std::string &resolvedPath)=0
virtual AR_API std::string Resolve(const std::string &path)=0
AR_API ArResolver()
virtual AR_API bool CreatePathForLayer(const std::string &path)=0
virtual AR_API bool IsRelativePath(const std::string &path)=0
Returns true if the given path is a relative path.
virtual AR_API bool IsSearchPath(const std::string &path)=0
Returns whether this path is a search path.
virtual AR_API ~ArResolver()
virtual AR_API void EndCacheScope(VtValue *cacheScopeData)=0
virtual AR_API void UnbindContext(const ArResolverContext &context, VtValue *bindingData)=0
virtual AR_API bool IsRepositoryPath(const std::string &path)=0
Returns true if the given path is a repository path.
virtual AR_API bool FetchToLocalResolvedPath(const std::string &path, const std::string &resolvedPath)=0
virtual AR_API std::shared_ptr< ArAsset > OpenAsset(const std::string &resolvedPath)=0
ArResolver & operator=(const ArResolver &)=delete
AR_API ArResolver & ArGetResolver()
virtual AR_API std::string ComputeRepositoryPath(const std::string &path)=0
Returns the computed repository path using the current resolver.
virtual AR_API std::string AnchorRelativePath(const std::string &anchorPath, const std::string &path)=0
virtual AR_API std::string ComputeNormalizedPath(const std::string &path)=0
Returns a normalized version of the given path.
AR_API void ArSetPreferredResolver(const std::string &resolverTypeName)
AR_API std::vector< TfType > ArGetAvailableResolvers()
virtual AR_API void BindContext(const ArResolverContext &context, VtValue *bindingData)=0
GLsizei const GLchar *const * path
Definition: glew.h:6461
GLsizei const GLchar *const * string
Definition: glew.h:1844
virtual AR_API ArResolverContext GetCurrentContext()=0
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
virtual AR_API void BeginCacheScope(VtValue *cacheScopeData)=0
AR_API ArResolver & ArGetUnderlyingResolver()
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
Definition: type.h:64
virtual AR_API void ConfigureResolverForAsset(const std::string &path)=0
Configures the resolver for a given asset path.
virtual AR_API void UpdateAssetInfo(const std::string &identifier, const std::string &filePath, const std::string &fileVersion, ArAssetInfo *assetInfo)=0
virtual AR_API ArResolverContext CreateDefaultContext()=0
virtual AR_API std::string GetExtension(const std::string &path)=0
Returns the normalized extension for the given path.
virtual AR_API std::string ResolveWithAssetInfo(const std::string &path, ArAssetInfo *assetInfo)=0
Definition: value.h:174
virtual AR_API bool CanCreateNewLayerWithIdentifier(const std::string &identifier, std::string *whyNot)=0
virtual AR_API bool CanWriteLayerToPath(const std::string &path, std::string *whyNot)=0