DOM guide: Resolving URIs

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

Working with URIs

Internally, the daeURI class resolves all relative URI references into full URIs before they're used by the COLLADA DOM for any operation, such as load or resolveElement.

Relative references require a base URI for resolution. The COLLADA DOM provides a base URI as follows:

• If the URI is found within a COLLADA document, then:
  • If the xml:base attribute is specified on the root <COLLADA> element, that value is used as the base URI.
  • If no xml:base is specified, the document's URI is used as the base 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 relative reference resolution.

Accessing URI Data

The daeURI class provides accessors to all 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 an unresolved relative reference if getURI is called before the relative reference is resolved. Relative references are resolved 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 reference was resolved.

• 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

To resolve a URI means to obtain a representation of the resource that the URI identifies. This should not be confused with resolving a relative URI reference, which means to convert a relative reference into a full URI. A lot of the URI literature uses the phrase resolve to refer to both processes, but the processes shouldn't be confused. Resolving relative URI references has already been discussed, and now we'll talk about resolving URIs.

In COLLADA, some URIs represent COLLADA elements, such as the url attribute on <instance_geometry> elements. The url is a URI that references a COLLADA <geometry> element. Some URIs represent resources that aren't COLLADA elements, such as the <image>/<init_from> element, which refers to an image file. As part of the document loading process, the COLLADA DOM attempts to resolve all URIs that represent COLLADA elements. The other URIs must be resolved manually by the client application.

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 the URI doesn't refer to a COLLADA element.
• 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.

The DOM automatically attempts to resolve all COLLADA element URIs that are found when loading a document, but if an application creates elements programmatically, you may encounter URIs that are in the uri_pending unresolved state. To be safe, always check daeURI::getElement for NULL. If NULL and daeURI::getState returns uri_pending, resolve the URI by calling daeURI::resolveElement.

Calling daeElement::resolveAll resolves all URIs in the COLLADA DOM that haven't been resolved yet. 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. You may set the URI to any valid URI reference, including absolute URIs and relative references. Relative URI references aren't resolved until necessary. Most commonly, this method is used to set URIs to reference other COLLADA elements. For example:

• Passing in a string "#myGeometry" creates a URI that references the element whose id is myGeometry from within the same document.
• Passing in a string "../subfolder/car.dae#wheel" creates a URI that references the element whose id is wheel in the external document car.dae.

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 that was set using 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 helpful if you have a reference to the element that 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 are 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. Then the DOM won't resolve any URIs that reference elements in external documents. Calling daeURI::getState to query the status of the URI returns the value uri_failed_external_document.

To retrieve a list of all documents to which the current document has external URI references, use daeDocument::getReferencedDocuments.

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

When a new document is loaded into the COLLADA DOM using 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.