Difference between revisions of "DOM resolver subsystem"

From COLLADA Public Wiki
Jump to navigation Jump to search
 
(6 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
==Purpose==
 
==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.
+
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==
 
==Default behavior==
Line 21: Line 21:
 
==Related classes and functions==
 
==Related classes and functions==
 
*DOM URI class: The class used to represent URIs in a [[COLLADA document]].
 
*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 resolver class: An interface to inherit from for creating URI resolvers.
 
 
{{editor|what=Check whether might be able to move some of the following into [[DOM guide: Resolving URIs]], or maybe some is already there and can be removed from here. }}
 
  
 
===DOM URI class (daeURI)===
 
===DOM URI class (daeURI)===
Line 30: Line 28:
 
URI strings are parsed in <code>internalSetURI</code>.
 
URI strings are parsed in <code>internalSetURI</code>.
  
The <code>baseURI</code> is constructed from the current working directory (cwd) (where available) when the <code>daeURI( int )</code> constructor is called.
+
The <code>baseURI</code> is constructed from the current working directory (cwd) when the <code>daeURI( int )</code> constructor is called.
  
 
The <code>daeElement</code> container is the element that holds the <code>daeURI</code> as either an attribute or value.
 
The <code>daeElement</code> container is the element that holds the <code>daeURI</code> as either an attribute or value.
Line 37: Line 35:
 
* When attempting to resolve the URI
 
* When attempting to resolve the URI
 
* In the <code>daeURI::daeURI(daeString uriString, daeBool nofrag)</code> constructor, when <code>noFrag</code> is set to true
 
* In the <code>daeURI::daeURI(daeString uriString, daeBool nofrag)</code> constructor, when <code>noFrag</code> is set to true
* When <code>daeURI::makeRelativePath</code> is called.
+
* When <code>daeURI::makeRelativePath</code> is called
  
 
<code>daeURI::validate</code> resolves relative URI references against one of (listed in priority):
 
<code>daeURI::validate</code> resolves relative URI references against one of (listed in priority):
Line 49: Line 47:
 
<code>daeURI::resolveElement</code> calls <code>daeURIResolver::attemptResolveElement</code>.
 
<code>daeURI::resolveElement</code> calls <code>daeURIResolver::attemptResolveElement</code>.
  
The URI state returns various URI status values, including:
+
The <code>daeURI::getState</code> method returns various URI status values, including:
* "empty": A default constructed URI.
+
* <code>uri_empty</code>: A default constructed URI.
* "loaded": A URI string exists but it hasn’t been normalized.
+
* <code>uri_loaded</code>: A URI reference exists, but it may still need to be resolved to a full URI.
* "pending": The URI is normalized but hasn't yet been resolved.
+
* <code>pending</code>: We have a full URI, but the URI hasn't been resolved to obtain a <code>daeElement</code> yet.
* "success", "failed_unsupprted_protocol", "failed_file_not_found", "failed_id_not_found", "failed_missing_containter", and "failed_external_document":  Possible states after <code>attemptResolve</code>. {{editor|what=[[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 <code>daeURI::getState</code> method returns"?}}
+
* <code>success</code>, <code>failed_unsupprted_protocol</code>, <code>failed_file_not_found</code>, <code>failed_id_not_found</code>, <code>failed_missing_containter</code>, and <code>failed_external_document</code>: Possible states after <code>attemptResolve</code>.
  
 
===DOM resolver class (daeURIResolver)===
 
===DOM resolver class (daeURIResolver)===
Line 61: Line 59:
 
* <code>daeLibxmlResolver</code> and <code>daeRawResolver</code> inherit from the DOM resolver base class, <code>daeURIResolver</code>.
 
* <code>daeLibxmlResolver</code> and <code>daeRawResolver</code> inherit from the DOM resolver base class, <code>daeURIResolver</code>.
  
* <code>_loadExternalDocuments</code> is a flag that an application can control for whether URI resolution loads documents.
+
* <code>_loadExternalDocuments</code> is a flag that an application can use to control whether URI resolution automatically loads documents.
  
 
* <code>attemptResolveElement</code> iterates over the list of <code>_KnownResolvers</code> and, if the protocol (URI scheme) and document extension are supported, it calls <code>resolveElement</code> on the resolver.
 
* <code>attemptResolveElement</code> iterates over the list of <code>_KnownResolvers</code> and, if the protocol (URI scheme) and document extension are supported, it calls <code>resolveElement</code> on the resolver.
Line 71: Line 69:
 
{{DOM navigation}}
 
{{DOM navigation}}
  
[[Category:DOM subsystems|Resolver subsystem]]
+
[[Category:COLLADA DOM|Resolver subsystem]]

Latest revision as of 23:48, 6 February 2008

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.

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, when noFrag 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 a daeElement yet.
  • success, failed_unsupprted_protocol, failed_file_not_found, failed_id_not_found, failed_missing_containter, and failed_external_document: Possible states after attemptResolve.

DOM resolver class (daeURIResolver)

Some internal notes about this class:

  • daeLibxmlResolver and daeRawResolver 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 calls resolveElement 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
Additional information:  • What's new  • Backward compatibility  • Future work
Terminology categories:  • COLLADA  • DOM  • XML