DOM meta system

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

Purpose

((ANDY: Details about why this system exists, why it is what/where it is, how it helps the user/developer.)) ((ELLEN: This system is the core of the COLLADA DOM. It is the whole ROS mentioned later in the user guide sections. It doesn't help the developer at all. 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 model

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 IO plugin ((ANDY: where does the plug-in come from?/where to find it?)) access an element’s data.

daeMetaElement and daeMetaAttribute

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

• daeMetaAttribute objects ((ANDY: is "object" correct here?)) and their variations ((ANDY: more later)), 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 that has URI data ((ANDY: how does it know?)) is marked ((ANDY: by whom/when/where?)) as _needsResolve. 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. ((ANDY: I'm not following why this is different from the next array; the order is 1, 2, 3, and the ordinal values would be 1,2,3--obviously a subtlety or coding convention that I'm not catching.))

Accompanying the _contents array is a parallel array _contentsOrder which stores ordinal values associated with the children. The base ordinal values for each child are 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.

The subclasses are named after the schema content model type that they are modeled after. i.e. daeMetaSequence represents an xs:sequence group.

daeMetaGroup is slightly special since 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 be then ((ANDY: "but then"?)) defers placing 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 type descriptions. ((ANDY, sorry, I don't know what a particle type is?))

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

The process is straight forward that it first searches for the type that the new type is based on. If it finds one it will add its ((ANDY: "it" referring to the new type or the type on which it's based?)) name to the binding list. If not then it creates a new rawRef type (I don’t think this every actually happens)

Enum types always generate a new type. The enum type also stores parallel arrays for the values and their string equivalents. ((ANDY: Are the values sometimes not sequential? e.g., I'd assume that an enum of "A", "B", "C" would have values of 1,2,3 (or 0, 1, 2); why is separate value needed?))

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.