What are Element Types?

DSM (Data Source Model) is a logical representation of a certain complex data source existing outside (such as a Java API, data file(s) or something else).

Each DSM contains elements. An element may have attributes and contain other elements (called children). Those notions are basically the same as in XML. The elements and attributes describe things (and their properties) contained in that external data source. The mapping of those external things on the elements/attributes of the DSM is called DSM Type. That mapping (or association) is maintained by a piece of code called DSM Type Driver.

The generator represents each DSM element with a GOMElement instance (see Generator Object Model | Object Types), where it holds all information known for that element. (The attributes may also have their object representation with instances of GOMAttribure, however it is rarely used.)

Each element is associated with a certain Element Type.

An Element Type (identified by a specific name) provides information about which attributes and which children an element associated with that type may have. Moreover, the Element Type also provides information for the DSM Type Driver about how to obtain those attributes and children from a particular GOMElement instance representing that element. So, generally, without knowing the Element Type, the DSM Type Driver is not able to obtain for a given element any data associated with it.

In certain DSM Types, some Element Types may extend other Element Types. In that case, an element may be associated not only with a single Element Type but with a whole set of Element Types involved in base/heir relationship. That set always contain a final heir, which is called exact Element Type of the given element. As the lowest heir of any other Element Types associated with the given element, the exact Element Type provides the ultimate information about the element (i.e. which kind of attributes and child elements can ever be retrieved from it and how). The exact Element Type is returned by GOMElement.elementType property (however, accessing it may evoke some extra calculations; see below).

Each element in the DSM can always be associated with the only exact Element Type. However, that association is not always explicitly available from the external data source. So, finding the exact Element Type for a given element may take some resources.


For example, in DocFlex/Javadoc, the entire Doclet API is mapped on Doclet DSM, which represents the Java API as a virtual XML document. That mapping is not the inherent feature of the Doclet API itself. Rather, it is maintained by Doclet DSM Driver. In that case, elements represent the objects returned by the Doclet API methods and Element Types correspond to the API Java interfaces. However, for a given object, it is not always immediately known the instance of which lowest Doclet API interface it is. To find out exactly, the object is needed to pass through a series of  instanceof  Java operators. This may take unnecessary processing, because knowing pecisely the lowest interface which this object is instance of may never be needed for further usage of that particular object.

Because of this, the association between an element and its Element Type is established dynamically and may be gradually refined down through the series of related Element Types during processing of the template.

When a DSM element represented by a GOMElement instance 'el' is found to comply with a certain Element Type 'ET', the generator remembers that association (stores it in el). After that, the el is said to be resolved with ET. Practically, it means that for this particular GOMElement instance, the generator will know how to obtain the attributes and children described by the Element Type 'ET'.

For example, if according to ET the element must has an attribute 'name', when el is resolved with ET, the expression:

el.getAttrValue("name")
is guarantied to return the value of that attribute. However, if since obtaining el, it has never been yet resolved with ET (or any of its descendants), the expression above may not properly return the attribute value, even though the compliance of the DSM element represented by el with the Element Type 'ET' does exist.

A GOMElement instance becomes resolved with a particular Element Type as soon as it has been tested somewhere to comply with that Element Type (or any of its descendants). This testing may happen in many ways, for instance, by calling instanceOf() function:

el.instanceOf("ET")
In many cases, for a given GOMElement instance, the generator already knows a certain Element Type with which it complies only from the way that instance was retrieved.

When a GOMElement instance representing a certain DSM element is resolved with the exact Element Type associated with that element (see above), it is said to have fully resolved Element Type.

See Also:

GOMElement.elementType, GOMElementType, instanceOf(), findElementType()