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

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.

URI state – "empty" is a default constructed URI.

URI state - "loaded" is when there is a URI string but it hasn’t been normalized.

URI strings are parsed in internalSetURI

validate is the function that normalizes a URI string.

The baseURI is constructed from the current working directory (cwd) (where available) when the daeURI( int ) constructor is called.

The daeElement container is the element that holds the daeURI as either an attribute or value.

validate normalizes the URI string against one of (listed in priority):

• The URI string passed in as an argument
• The documentURI (taken from the container element if present)
• The static baseURI (cwd)

URI state – pending is after the URI is normalized but before it is resolved

validate is called when attempting to resolve the URI, in the copy constructor, when the noFrag flag is true in the constructor, when attempting to makeRelativePath, during resolveURI.

The DOM always operates on fully normalized absolute URIs.

resolveElement calls daeURIResolver attemptResolveElement (see below)

URI state – success, failed_unsupprted_protocol, failed_file_not_found, failed_id_not_found, failed_missing_containter, and failed_external_document are all valid states after attemptResolve.

DOM resolver class (daeURIResolver)

Some internal notes about this class:

• daeLibxmlResolver and daeRawResolver inherit from the DOM resolver base class, daeURIResolver.

• _KnownResolvers is a static list of current resolvers to use to attempt to resolve a URI. The constructor for daeURIResolver adds itself to the static list.

• _loadExternalDocuments is the flag that a user can control for whether URI resolution loads documents.

• attemptResolveElement iterates over the list of known resolvers and, if the protocol (URI scheme) and document extension are supported, it calls resolveElement on the concrete resolver.

((EDITOR: This page needs the following improvement: what is a "concrete 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.