DOM guide: Resolving URIs
|DOM 1.3||This revision of this article is current for COLLADA DOM version 1.3.|
Working with URIs
daeURI class resolves all relative URI references into full URIs before they're used by the COLLADA DOM for any operation, such as
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.
Accessing URI Data
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
getURIis called before the relative reference is resolved. Relative references are resolved when they are needed for an operation, for example, in
resolveElementor 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
daeURIobject and need to find its context or check which document it belongs to.
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::getStateprovides 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::resolveElementresolves 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
uri_pending, resolve the URI by 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::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
myGeometryfrom within the same document.
- Passing in a string "
../subfolder/car.dae#wheel" creates a URI that references the element whose id is
wheelin the external document
Note: It is the client's responsibility to ensure that strings passed to
daeURI::setURI are valid URI strings.
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
To retrieve a list of all documents to which the current document has external URI references, use
To retrieve a list of pointers to the
daeURI objects that reference a specific document, use
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.
|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