DOM guide: Architecture
The following diagram shows the components and communication flow of COLLADA DOM.
Figure 1 The COLLADA DOM (TODO: make a new drawing)
The DAE interface provides the means through which applications interact with the COLLADA DOM. This interface provides document load and save functionality, access to the runtime database, access to the object model, and is also used to register integration objects.
The COLLADA Object Model is a set of C++ objects (COLLADA "dom*" objects) generated directly from the COLLADA schema. Each COLLADA "dom*" object derives from a specialized base class designed to provide reflectivity and robustness to the API. The generated object model is the basis of the runtime database, and is a C++ representation of the COLLADA schema elements.
The Runtime Database is a resident, active cache of COLLADA elements. This cache is based on C++ COLLADA elements handed to the cache by the COLLADA Backend.
The COLLADA backend consists of the components responsible for translating external COLLADA instance data into C++ runtime COLLADA objects. The default backend uses the libxml2 library to intelligently parse and translate teh XML instance data.
External Instance Data
The nonresident storage of COLLADA instance documents or databases.
The DAE class provides a simple, general-purpose interface to the replaceable COLLADA backend and runtime database. This class serves as a wrapper for the entire pipeline, ensuring a consistent interface regardless of extensions to or replacements for the various DOM components. The following is a subset of the public database-interface API. The complete API is defined in dae.h.
virtual daeInt setDatabase(daeDatabase* database); virtual daeInt load(daeString name); virtual daeInt saveAs(daeString fileName, daeString collectionName); virtual daeInt unload(daeString name);
The COLLADA DOM was designed to allow the underlying database mechanism to be supplemented or replaced without affecting performance of the rest of the API components. The included front-end interface hands off generic queries through the API to any configured backend. Query results assembled by the backend are handed back to the runtime database for delivery in response to the original query. In addition, the front-end interface itself could be extended to provide a more robust or specific query feature set.
The COLLADA DOM is built upon a C++ object model that includes a reflective object system (ROS) and an object model that corresponds directly to the COLLADA XML schema definition (see “Figure 2 The COLLADA Object Model”).
Reflective Object System (ROS)
The COLLADA DOM is built upon a set of functionality that defines a self-managed, reflective object system (ROS). The ROS creates, manages, and manipulates DOM objects and the data that define their structure (meta-data) and contents. The ROS is configured with metadata that, for COLLADA, defines the COLLADA Object Model. The COLLADA Object Model classes are created by the ROS at runtime, loaded with instance data, and passed to the runtime database (see “Runtime Database”).
COLLADA Object Model
The COLLADA Object Model is a C++ equivalent representation of the elements defined in the COLLADA schema. The entire Object Model class hierarchy is auto-generated using a code generator that translates the COLLADA schema element definitions into C++ classes. Code generation of the COLLADA Object Model structures guarantees consistency with the schema and accuracy of the code. Every COLLADA Object Model class is prefixed with "dom". The code generation builds in registration of meta-information about the structure of each element in the COLLADA Object Model. Via the static method registerElement() contained in every COLLADA Object Model class, the metadata about an element and its subelements are registered with the ROS, allowing it to understand, track, and manage each COLLADA DOM object.
Figure 2 The COLLADA Object Model (TODO: make new figure)
At the heart of the COLLADA DOM is a runtime database, a resident cache of COLLADA elements. The runtime database is implemented as a C++ object, daeDatabase, with a virtual interface. The runtime database allows for simple requests of COLLADA objects by name, type, document, or any combination of the three through the database interface.
Figure 3 The COLLADA Runtime Database (TODO: make a new figure)
Database Query Manager
The COLLADA DOM does not include a query manager at this time, but it warrants mention because the addition of this component may be a useful extension to the runtime database. The COLLADA backend is essentially a wrapper providing access to a persistent data store. While the provided mechanism uses local XML files, it is expected that extensions for binary file formats as well as full database systems will be implemented. An intelligent query manager in the runtime database could cooperate with a particular backend data store to optimize query and retrieval of data for a particular application. The API has attempted to facilitate these extensions.
The COLLADA backend consists of an abstract class, daeIOPlugin, with a virtual interface for reading and writing COLLADA to and from a persistent data store. Included with the API is one implementation, daeLIBXMLPlugin, which uses the libxml2 library to provide fully standards-compliant XML document loading. It is expected that other implementations of this interface would yield I/O modules for other types of persistent data stores, for example: binary files and database systems.
The COLLADA integration library is a set of generated template classes that exactly mirror the DOM objects. Every integration class is prefixed with int. Each integration class derives from a base class, daeIntegrationObject, which provides a virtual interface that defines the semantics for translation of COLLADA data to application structures. Starting with the COLLADA DOM integration library, developers need only define object equivalence by filling in translation functions from one C++ structure to another. See DOM Guide: Integration Templates for an example of how the integration library templates can be used.