DOM meta system

Summary: The COLLADA DOM meta system is a series of classes that make up the reflective object system. This system provides the type information for all COLLADA elements in the COLLADA DOM.

Purpose

This system is the core of the COLLADA DOM. It is the whole Reflective Object System. No developers really need to deal with these objects directly. These objects exist under the hood to allow the DOM to do what the DOM does.

How it works

Element descriptions

Each daeElement has a nonstatic pointer to its type information: _meta.

Each strongly typed class inherits from daeElement and has a static pointer to the type information: _Meta.

Each element can have its own element name. If getElementName returns NULL then the element’s name is the same as its type name (its daeMetaElement’s name ).

Reflective Object System

The daeElement class is the base class for the following:

• all strongly typed elements and xs:group elements. It has storage for very little data; instead, the strongly typed subclasses provide storage for the data that is needed.

• reference counted objects. INTERNAL NOTE: This should be changed, however; see DOM future work#Class hierarchy reorganization.

The meta system allows access to a strongly typed subclass’s data given a daeElement base class object by storing pointer offsets from the daeElement pointer to the data. This is how all of the “dae” library functions and the libxml2 I/O plug-in access an element’s data. <nowiki>Insert non-formatted text here</nowiki>

daeMetaElement and daeMetaAttribute

daeMetaElement is the main class for an element’s type description. It stores:

• daeMetaAttribute objects and their variations, for each attribute, value, element child, and some auxiliary data (like the _contents arrays).

• a tree of daeMetaCMPolicy objects that dictate the behavior and ordering of an element’s children.

• the pointer offset to the data that it describes.

daeMetaAttribute, in turn, stores type information for the data that an element contains.

The value of an element is just a daeMetaAttribute that is kept separately from the attribute list.

daeMetaAttribute is the base class for daeMetaAttributeArray. These two classes represent single values and arrays of values respectively.

daeMetaElementAttribute and daeMetaElementArrayAttribute are types of daeMetaAttributes where the value is another element instead of a data type. They also inherit from daeMetaCMPolicy and are part of the content model tree.

getWritableMemory returns a raw (byte) pointer to the data. This pointer needs to be cast appropriately to be used.

Any type in the COLLADA schema that has URI data is marked as _needsResolve in the code generator when generating the classes for the COLLADA DOM. The metaAttributes for the data is stored in the _resolvers array.

Calling resolve on a metaAttribute in turn calls resolve on the atomic type for the data the attribute describes. Only resolver and idresolver (uri and idref) types implement functionality for resolve.

daeMetaCMPolicy

daeMetaCMPolicy and its subclasses were added to control the ordering of children.

Elements that contain complex content models or content models with an <xs:choice> will have an array (_contents) that stores the order of these children. Accompanying the _contents array is a parallel array _contentsOrder, which stores ordinal values associated with the children. The base ordinal value for each child is calculated during code generation. The actual ordinal value given to a child is calculated at runtime. Children with a higher ordinal value get placed after children with lower ordinal values.

placeElement, removeElement, findChild, and getChildren are all recursive functions where the behavior is defined by the subclasses, which are named after the schema content model type that they are modeled after. For example, daeMetaSequence represents an <xs:sequence> group. Also note:

• daeMetaGroup is slightly special because it contains a daeMetaElementAttribute that represents the group daeElement that needs to be placed. It has placing logic to place the group element in the parent element but then defers the placing of the child to the group element.
• daeMetaChoice requires some additional per-object data. This data is stored as a char array in daeElement. Each choice is numbered and the value in the array at the numbered index represents which “choice” has been chosen for its children. A -1 represents that no subtrees have been populated yet.

Particle type descriptions

daeAtomicType is the base class for all particle (XML) type descriptions.

The code generator can generate new types. They are registered in the registerDomTypes function in domTypes.cpp.

The process is straight forward. For each new type defined in the schema, the function first searches for the type from which the new type is derived. If it finds a descriptor for the base type, it adds the new type's name to the binding list. If the base type is not found, then a new rawRef type is created (I don’t think this ever actually happens).

Enum types always generate a new type. The enum type also stores parallel arrays for the values (as the values are not guaranteed to be sequential) and their string equivalents.

The daeResolverType represents types of daeURI. The memoryToString and stringToMemory functions currently are where special characters are handled. Memory to string is also where there is logic to output only URI fragments instead of full URIs for same document references.