FlexDoc/Javadoc - JavadocClassic - Templates

Initialization Subtemplates

init.tpl

This template produces no output. Instead, it is called only once from either SingleDoc.tpl or FramedDoc.tpl main templates before any other processing starts. The template's job is to create element maps.

Element maps are essentially hash-maps. They map keys to sets of Doclet DSM's elements (which represent the objects operated by Doclet API). Most commonly, as the keys are used the element unique identifiers (see GOMElement.id), which means that some sets of elements are mapped to other sets of elements. This can be used to quickly find by certain elements some other elements according to specific functional relations. That makes possible resolving very complicated queries and provides capabilities for sophisticated data mining.

Here's an example. From the Java source code (via the Doclet API), we can easily obtain the following things:

  1. The list of all classes in the project
  2. For a given class: its superclass and the list of all interfaces it directly implements
  3. For a given interface: the list of all interfaces it directly extends
Now, for a given interface, we want to know: Which classes in the project do directly or indirectly implement it? Apparently, the answer is implicitly contained in all those items above. But how to find it?

Using an element map, it is possible. The element map is created as follows:

  1. All included classes and their superclasses are iterated.
  2. For each class, we find all interfaces that this class directly or indirectly implements.
  3. For each found interface and the class implementing it, we add a mapping so that the interface's element ID becomes a key and the element representing the class is put in the map by that key.
As a result, we have an element map that maps each interface to the list of all known classes implementing it. The following screenshots show the init.tpl template (click to enlarge) and how the creating of such an element map is programmed:

On the screenshot above, the function prepareElementMap() puts in the element map "all-known-implementing-classes" a single element representing a class, however, by several keys at once. Those keys are the unique identifiers of all interfaces that the class directly or indirectly implements. The list of interfaces is obtained using Location Rules. The function getElementIds() converts the enumeration of elements (representing the found interfaces) into an array of their unique IDs.

The "all-known-implementing-classes" element map is further used within the class.tpl template to generate that very list for a particular interface.

You can find a lot more information about Element Maps, Location Rules and the functions to work with them at: Template Designer | Help | Assistant... | Functions | By Category | “Elements / Attributes” | “Element Maps” and “Location Paths & Rules”.

Template Location:

{flexdoc-javadoc}/templates/classic/lib/init.tpl

Called From:

FramedDoc.tpl, SingleDoc.tpl