Ecore2HTML

Bx Examples Repository

Title: Ecore2HTML

Version: 0.1

Type:

Industrial, Sketch

Overview

This example is a bidirectional model-to-text transformation between class diagrams and a corresponding HTML documentation. It is meant to be very simple but at the same time realistic and still able to showcase the advantages of using a BX language instead of a standard programming language.
The left and right artefacts are also chosen to be as realistic as possible (not necessarily metamodels or graphs) so that a variety of BX tools (that for instance work directly on the XML/text level) can be used.

Models

A left model $$m$$ is a class diagram conforming to the Ecore metamodel. The figure below depicts an exemplary class diagram consisting of packages and classes, representing together the architecture of a TGG-tool.

A right model $$n$$ is a file structure consisting of folders and HTML documents as depicted below:

Consistency

The figures in the Models section constitute a consistent pair of $$m$$ and $$n$$ .

In more detail, $$R(m,n)$$ iff

For each package in $$m$$ , there is a corresponding folder in $$n$$ with an HTML document for the package (e.g., for the TGGLangugage package in $$m$$ we have a TGGLanguage folder in $$n$$ with the HTML document _TGGLanguage.html).
The HTML document of a package includes the name of the package and a list of its contained classes (e.g., the HTML document _precompiler.html contains a list consisting of one class, namely RefinementPrecompiler). Furthermore, it must be clear from the header in the HTML file if the corresponding package is the outermost package or a subpackage.
The containment hierarchy of packages in $$m$$ are the same as the folder hierarchy in $$n$$ (e.g., the precompiler folder is contained in the TGGLanguage folder as the precompiler package is contained in the TGGLanguage package).
For each class in $$m$$ , there is a corresponding HTML document including the name of the class and a table listing all of its methods excluding inherited methods. The table should at least have a column for the names of the methods, and a column for a corresponding textual description of the methods.
The HTML document of a class is contained in the folder corresponding to its package (e.g., RefinementPrecompiler.html is contained in the precompiler folder as the RefinementPrecompiler class is contained in the precompiler package).

We leave the exact look of the HTML files to the transformation designer.

Consistency Restoration

Backward

An important delta in a right model $$n$$ is editing the textual descriptions in the HTML documents, i.e. documenting the classes, packages, and methods. Change propagation in this case should not change the class diagram at all, i.e., the features that are not reproducible from an HTML document such as inheritance relations, references, or properties must all be preserved.

Forward

A left model $$m$$ can be modified by moving a package (with its entire content) into another package. In this case, the corresponding folders and HTML documents must be moved such that the same hierarchy is again reflected in $$n$$ . The textual descriptions that are not reproducible from the class diagram must be preserved. Note that an outermost package might become a subpackage and vice-versa. In this case the heading of the corresponding documentation file must be adjusted to reflect this.
A further change is moving methods from one class to another. This should be handled similarly, preserving as much documentation as possible.

Properties

The formal properties the example focuses on are:

hippocraticness (in the backward direction)
least change (in the forward direction)
correctness (are the results of the synchronization consistent?)

Variants

The example can be extended to cover properties of classes (structural features in Ecore lingo).

Inheritance could be documented.

An interesting extension is to demand that the method tables contain not only the methods implemented directly in a certain class, but also all inherited class. This corresponds to a transitive closure over the inheritance relation and requires, for example, an advanced TGG language feature. Other BX languages might have no problems with this.

The example can be converted into a benchmark (if we get enough implementations) by crawling open source projects (OpenJDK, Eclipse, Apache) and extracting real-world class diagrams as left models.

Discussion

Information loss is incurred when transforming class diagrams to documentation models (e.g., inheritance relations, references, and properties are left out of documents) and when transforming documentation models to class diagrams (all textual class, package, and method descriptions in the documents would be lost!). This is the main reason why the change propagation strategy required for this example must take the old version of the respective output artefact into account.

References

A TGG solution to the case study can be accessed via a virtual machine in SHARE.

This can be seen as a possible formalization of the example that hammers out all details.
Feel free, however, to implement the example in a way that better fits your tool/approach.

—-

A FunnyQT solution is here. It implements the variant where there are only classes and documents. For each class, there is a corresponding document. The classes form a generalization hierarchy, and documents link to the corresponding super- and subclass documents. Furthermore, documents also link (with a different link type) to all their super- and subclasses' documents directly (transitive closure over the generalization relation in the class model).

Author(s)

Anthony Anjorin, Erhan Leblebici

Reviewer(s)

None yet.

Comments