DOM guide: Resolving URIs

The daeURI class represents URI data types in the COLLADA DOM. The daeURI class provides an interface for accessing/manipulating the URI string and for resolving the URI reference.

Working with daeURI

The COLLADA DOM uses normalized absolute URIs only. The daeURI class contains code that converts relative URIs into absolute URIs.

The base URI syntax is

scheme://authority/filepath?query#fragment

An absolute URI contains a scheme and an authority. If the authority is left empty than localhost is used, i.e.

file:///c:/path/document.dae#Geo_01

is a URI that references a file named document.dae on the localhost found in c:/path.

The fragment portion is used to identify elements by using their "id" attribute. The previous example references an element with an id "Geo_01".

A relative URI is any URI that does not contain a scheme and authority.

A relative URI can be a relative path, an absolute path, or just a fragment.

Examples of relative path URIs:

./path/document.dae
../../../path/document.dae#elementID
document.dae#Geo_01

An absolute path must be preceded by a forward slash character '/'. An example:

/c:/path/document.dae#Light01

A fragment identifier references an element that can be found within the same document as the URI. An example of this:

#redMaterial

The COLLADA DOM parses URI strings and normalizes them into absolute URIs before it can use the URI for any operation, i.e. load or resolveElement.

A base URI is needed to normalize relative URIs. Absolute URIs do not require a separate base URI. The COLLADA DOM will provide a base URI. If the URI is found within a COLLADA document then the base URI will be the document URI. If the URI is not part of a document then the current working directory is used as the base URI.

Assuming a base URI of

file:///c:/A/B/C/D/doc.dae

here are some examples of how the following URIs will be normalized:

./path/document.dae  =>  file:///c:/A/B/C/D/path/document.dae
../../../path/document.dae#elementID  =>  file:///A/path/document.dae#elementID
/c:/path/document.dae#Light01  => file:///c:/path/document.dae#Light01
c:/path/document.dae  =>  file:///c:/A/B/C/D/c:/path/document.dae

Note that Windows file paths ARE NOT proper absolute path relative URIs! Note also that only the '/' character is used as a path delimeter. Windows uses the '\' character to delimit path segments. Using '\' character can result in incorrect URI processing! "A\B\C" is considered one path segment. If using "file:///A\B\C" as a base URI and trying to resolve "../doc.dae" the result will be "file:///doc.dae" and NOT "file:///A\B\doc.dae" as one might have expected.

Creating URI Strings

The COLLADA DOM provides two ways to create URI strings; by setting the string directly with daeURI::setURI or by using the daeURI::resolveURI method.

Calling daeURI::setURI allows you to pass in a new URI string to be used for the daeURI. The daeURI class will parse this string right away but will not normalize the new URI until it is needed. You may set the URI to any valid URI string, absolute or relative. Most commonly URIs are set to reference other COLLADA elements.

• Passing in a string "#elementID" will create a URI that references the elementID element from within the same document.
• Passing in a string "rel-path/document#elementID" will create a URI that references an element in an external document.

Note. It is the clients responsibility to ensure that strings passed into daeURI::setURI are valid URI strings.

Calling daeURI::resolveURI will create a URI string based on the element set with daeURI::setElement. The COLLADA DOM will create the URI based on the element's documentURI and the element's ID. This method of setting URI strings is very helpful if you have a reference to the element you wish to make the URI reference. Doing so will prevent the need of custom URI string generation. Here is an example of how this works:

//inst_geom is a pointer to an existing domInstance_geometry element
//geom is a pointer to an existing domGeometry element.
inst_geom->getUrl().setElement( geom );
inst_geom->getUrl().resolveURI();

External URI References

By default, the COLLADA DOM will load additional COLLADA documents to resolve external URI references. I will be refering to these COLLADA documents as "external documents". Client applications may want or need finer control over which documents are loaded and when.

The COLLADA DOM provides this functionality with daeURIResolver::setAutoLoadExternalDocuments and various methods of daeDocument class. To disable the DOM from implicitely loading documents when resolving URIs you must call

daeURIResolver::setAutoLoadExternalDocuments( false );

sometime before you attempt to load a document.

All URIs that reference elements in external documents will not be resolved. You will be returned the value uri_failed_external_document when querying the status of the URI by calling daeURI::getState.

Use daeDocument::getReferencedDocuments to retrieve a list of all documents that the current document has external URI references to.

Use daeDocument::getExternalURIs to retrieve a list of pointers to the daeURI objects that reference a specific document.

When a new document is loaded into the COLLADA DOM, via DAE::load, the COLLADA DOM checks if any currently loaded documents contain any external references to the newly loaded document. If a document does contain an external reference to the newly loaded document the reference is resolved.