DOM resolver subsystem
Summary: The resolver subsystem manages the resolution of URIs based on a URI's scheme and filename extensions.
The resolver subsystem allows for custom URI resolvers to be written and added to the COLLADA DOM. These resolvers can be used to load various types of external references-- for example, binary representations of mesh data--or to provide access to different data systems--for example, using a database to access elements.
By default, the COLLADA DOM has only two resolvers:
- The main resolver,
daeLIBXMLResolver, resolves elements from COLLADA documents (.dae or .xml) with the file or http URI scheme. This can resolve elements from the same document or external document references.
- The newly added DOM raw resolver class,
daeRawResolver, resolves only .raw files with the file URI scheme.
Instantiating an object of a class that inherits from
daeURIResolver adds a custom resolver to the COLLADA DOM.
How it works
The base class
daeURIResolver contains a static array named
_KnownResolvers that contains resolvers. The constuctor for
daeURIResolver adds a reference to this to this list of resolvers. When a DOM URI class attempts to resolve itself, it searches through the
_KnownResolvers list for a resolver that matches its URI scheme and file extension. When an appropriate resolver is found, the resolver is then asked to resolve the current URI.
Related classes and functions
- DOM URI class: The class used to represent URIs in a COLLADA document.
- DOM resolver class: An interface to inherit from for creating URI resolvers.
DOM URI class (daeURI)
URI strings are parsed in
baseURI is constructed from the current working directory (cwd) (where available) when the
daeURI( int ) constructor is called.
daeElement container is the element that holds the
daeURI as either an attribute or value.
validate method normalizes a URI string. It is called when attempting to resolve the URI, in the copy constructor, when the
noFrag flag is true in the constructor, when attempting to
((EDITOR: This page needs the following improvement: If this is a list of 5 different things, change to bulleted list. If fewer than 5, make into list with items combined appropriately. ))
It normalizes the URI string against one of (listed in priority):
- The URI string passed in as an argument
documentURI(taken from the container element if present)
- The static baseURI (cwd)
The DOM always operates on fully normalized absolute URIs.
The URI state returns various URI status values, including:
- "empty": A default constructed URI.
- "loaded": A URI string exists but it hasn’t been normalized.
- "pending": The URI is normalized but hasn't yet been resolved.
- "success", "failed_unsupprted_protocol", "failed_file_not_found", "failed_id_not_found", "failed_missing_containter", and "failed_external_document": Possible states after
((EDITOR: This page needs the following improvement: DOM guide: Resolving URIs mentions states like "uri_pending, uri_failed_*", and so on. Are these the same ones? If so, fix either these or those to correct values. Also, can we replace "the URI state returns" with "The
daeURI::getState method returns"? ))
DOM resolver class (daeURIResolver)
Some internal notes about this class:
daeRawResolverinherit from the DOM resolver base class,
_loadExternalDocumentsis a flag that an application can control for whether URI resolution loads documents.
attemptResolveElementiterates over the list of
_KnownResolversand, if the protocol (URI scheme) and document extension are supported, it calls
resolveElementon the resolver.
attemptResolveURI is never called. It is dead.
Future: This is a good system but the program flow should be structured differently. See DOM future work.
|COLLADA DOM - Version 2.4 Historical Reference|
|List of main articles under the DOM portal.|
|User Guide chapters: • Intro • Architecture • Setting up • Working with documents • Creating docs • Importing docs • Representing elements • Working with elements • Resolving URIs • Resolving SIDs • Using custom COLLADA data • Integration templates • Error handling|
Systems: • URI resolver • Meta • Load/save flow • Runtime database • Memory • StringRef • Code generator