DOM resolver subsystem
Summary: The resolver subsystem manages the resolution of URIs based on a URI's scheme and filename extensions.
Purpose
The resolver subsystem allows 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.
Default behavior
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)
The DOM URI class, daeURI
, is part of the DOM resolver subsystem. It represents a URI data type in a COLLADA document. Some internal notes about the class:
URI strings are parsed in internalSetURI
.
The baseURI
is constructed from the current working directory (cwd) when the daeURI( int )
constructor is called.
The daeElement
container is the element that holds the daeURI
as either an attribute or value.
The validate
method resolves relative URI references. It is called in the following situations:
- When attempting to resolve the URI
- In the
daeURI::daeURI(daeString uriString, daeBool nofrag)
constructor, whennoFrag
is set to true - When
daeURI::makeRelativePath
is called
daeURI::validate
resolves relative URI references against one of (listed in priority):
- The URI string passed in as an argument
- The xml:base attribute on the root <COLLADA> element of the containing document
- The
documentURI
(taken from the container element if present) - The current working directory
The DOM always operates on absolute URIs.
daeURI::resolveElement
calls daeURIResolver::attemptResolveElement
.
The daeURI::getState
method returns various URI status values, including:
uri_empty
: A default constructed URI.uri_loaded
: A URI reference exists, but it may still need to be resolved to a full URI.pending
: We have a full URI, but the URI hasn't been resolved to obtain adaeElement
yet.success
,failed_unsupprted_protocol
,failed_file_not_found
,failed_id_not_found
,failed_missing_containter
, andfailed_external_document
: Possible states afterattemptResolve
.
DOM resolver class (daeURIResolver)
Some internal notes about this class:
daeLibxmlResolver
anddaeRawResolver
inherit from the DOM resolver base class,daeURIResolver
.
_loadExternalDocuments
is a flag that an application can use to control whether URI resolution automatically loads documents.
attemptResolveElement
iterates over the list of_KnownResolvers
and, if the protocol (URI scheme) and document extension are supported, it callsresolveElement
on the resolver.
Note: 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 |