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

Working with URIs

The COLLADA DOM uses normalized absolute URIs only. The daeURI class contains code that converts relative URIs into absolute URIs. It must do this before it can use the URI for any operation, such as load or resolveElement.

The COLLADA DOM parses URI strings and normalizes them into absolute URIs. Relative URIs require a base URI for normalization. The COLLADA DOM provides a base URI as follows:

• If the URI is found within a COLLADA document then the base URI is the document URI.
• If the URI is not part of a document then the current working directory is the base URI.

Read main discussion on COLLADA URIs and normalizing.

((EDITOR: This page needs the following improvement: figure out where to merge this in here: "If the authority is left empty than localhost is used. " ))

Accessing URI Data

The daeURI class provides accessors to all of the parts of a parsed URI. Note that the COLLADA DOM refers to the scheme as protocol and the fragment as id. Useful methods include:

• daeURI::getURI, which returns the full URI string. This may be the nonnormalized URI string if getURI is called before the URI is normalized. URIs are normalized when they are needed for an operation, for example, in resolveElement or when loading a document.

• daeURI::getOriginalURI, which returns the original URI string either read from the document or supplied by the user before the URI was normalized.

• daeURI::getContainer, which returns a reference to the element that contains this URI data. This is helpful if you are given a daeURI object and need to find its context or check which document it belongs to.

Resolving URIs

As part of the document loading process, the COLLADA DOM attempts to resolve all of the URIs that are loaded.

Useful methods related to resolving URIs include the following:

• daeURI::getElement, if successful, returns the element that a URI resolves to. If this returns NULL then there could have been an error attempting to resolve the URI or there hasn't been an attempt at all.
• daeURI::getState provides the status of the URI. Returned values include:
  • uri_failed_*: There was an error resolving the URI.
  • uri_pending: There hasn't been an attempt to resolve the URI.

• daeURI::resolveElement resolves a URI.

All URIs that are found in a document upon load will attempt to resolve, but if an application creates elements programmatically, you may encounter URIs that are in the uri_pending unresolved state. To be safe, you should always check daeURI::getElement for NULL and, if NULL, check the state and, if needed, attempt to resolve the URI manually by calling daeURI::resolveElement.

If there have been many elements that have been created, calling daeElement::resolveAll will resolve all URIs that are present in those newly created elements. An application that creates new elements and intends to pass COLLADA DOM data between different systems, like a conditioner in the COLLADA Refinery, would benefit from calling daeElement::resolveAll before finishing. This could avoid common errors in which applications assume that all URIs have attempted to be resolved.

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 parses this string right away but does 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" creates a URI that references the elementID element from within the same document.
• Passing in a string "rel-path/document#elementID" creates a URI that references an element in an external document.

Note: It is the client's responsibility to ensure that strings passed to daeURI::setURI are valid URI strings.

Calling daeURI::resolveURI creates a URI string based on the element set with daeURI::setElement. The COLLADA DOM creates 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 makes custom URI string generation unnecessary. 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 loads additional COLLADA documents to resolve external URI references. These COLLADA documents will be referred to 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 the daeDocument class. To disable the DOM from implicitly 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 whether 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.