Developers' Notes: Generating HTML Documentation

With Data Designer, one can add on modules that extend its functionality.  This modularity is provided via OSGI plug-ins, which Data Designer's architecture is based on.

We provided the ability to generate artefacts based on metadata from an ECore meta-model through two such modules.  At the end of 'Data Designer: Creating and Managing Metadata' we mentioned how one plug-in has been created to generate documentation as a single web-page and another for XML schema document generation to validate data.  These examples are based specifically on the Prudential Regulation Authority’s Firm Data Submission Framework(FDSF) data model. 

To generate HTML markup, we used the Rendersnake library instead of using string templates or markup generators. This library provides the ability to create reusable HTML components while validating them at run time. Having HTML components that are reusable allows us to create one set of Java classes that can be reused to generate documentation for different sets of metadata or even different ECore data models. 

The following assumes some basic knowledge of the Eclipse Modeling Framework's api.

EMF provides runtime Java objects for both meta-models and metadata.  These are cast as EObjects at runtime.  Within the plugin, all metadata is added to a HashMap where we create a unique list of EObjects (the HashMap's value) for every class (the HashMap's key) from the meta-model (figure 1). 

if (hashMap.containsKey(className)) {
 // check to see if the list already contains the current eObject
 if (!hashMap.get(className).contains(eObject)) {
  hashMap.get(className).add(eObject);
 }
} else {
 EList<EObject> eList = new BasicEList<EObject>();
 eList.add(eObject);
 hashMap.put(className, eList);
}

Figure 1: Adding an EObject to a HashMap

Now we have created lists for every class that contains every element we would like to include in our HTML documentation. We can create HTML components using Rendersnake's API for each unique list. For example, we have a requirement to display all Contexts from the FDSF data model as well as all other model elements required by a Context, such as Measures and Dimensions (i.e., enumerations). Below is a code snippet from a Java class that will render all Contexts from the FDSF data model.

EList<EObjects> Contexts;
for (int i = 0; i < contexts.size(); i++) {
 EObject context = contexts.get(i);
 html.h3().content(HTMLUtils.getName(context));
 html.p().content(HTMLUtils.getDefinition(context));
…

Figure 2: Rendering Contexts

What the code above will create is a header (<h3>) and a paragraph (<p>) for every Context from the list in  the HTML page. Figure 3 shows a rendered example of what figure 2's code snippet above will create.

Those with experience in EMF might wonder why we have chosen to implement HTML generation using dynamic EMF code instead of POJO's generated through EMF.  The plug-in is implemented using dynamic EMF so the code can be quickly refactored for other data elements and even different data models.  Although dynamic EMF requires more programming effort (more lines of code) initially, binding the plug-in's code to model-specific POJO's would require a lot more effort to refactor when we wish to use it again for another model.

The full example of the Firm Data Submission Framework can be seen here.

Figure 3: An example excerpt from generated HTML documentation