Occasionally I receive requests from people looking for a simple way to generate a report from an XMI file. For example, they may need to collect a list of all class attributes that satisfy a certain condition, and write them to some HTML or XML file. Depending on the task at hand, XSLT could work in such situations, especially if it’s a one-off problem to solve, the XMI files are not very large, and come from a single source. Another option is to use the report generation facilities that some UML modeling tools offer.

But what if you’re dealing with huge XMI files, possibly from different sources? Or the report depends on information contained in proprietary XMI extensions that your UML modeling tool does not import? Or you need to evaluate complex conditions or constraints on the UML model elements for the report? That’s what SDMetrics was designed for. However, SDMetrics does not have a report generation facility. You could use SDMetrics’ API and write a Java program to generate the report. That requires Java skills, and the solution must be recompiled and redeployed every time the report needs to be changed. A more flexible solution is to use a Java-based template engine such as Velocity for report generation.

In this post, we will develop a Velocity template for SDMetrics to generate an HTML report for a UML model. The report will list

every UML model element in the model, along with the values of its attributes,

the metric values for each model element,

the contents of the helper sets for each model element (for example, the set of ancestor/descendant elements),

the list of rule violations of the model element, if any.

Here’s a preview of what the report will look like. In this form, the report is not yet particularly useful or appealing. However, the main purpose of this post is to demonstrate how to include all the model information in the report using the SDMetrics API. The template we are about to write can thus serve as a starting point for developing customized reports more quickly.

We also need a Java compiler or IDE to compile the glue code that hooks up Velocity with the SDMetrics API, and a Java 1.7 runtime for execution. I have prepared a ZIP archive for download that contains the libraries, glue code, and the finished template, ready to compile and run.

Define a report facade

Java template engines provide a scripting language to access Java objects, and invoke methods on these objects to traverse the data structures for the report. In the SDMetrics API, the interesting Java classes for report generation are:

I found it useful to implement a single Java class that serves as facade to the container classes (MetaModel, Model, MetricStore, MetricsEngine, RuleEngine). That way, the report template author does not have to deal with these five objects individually, but can rely on a single class that provides all the data. Let’s call this class ReportFacade. Here’s an excerpt from the class:

The methods of the facade class mostly just delegate to the respective getter methods of the container classes. Where necessary, objects are filtered or placed into collections so that the report template can access them.

Creating the report structure

Let’s start with the template. The following code snippet generates the overall structure of the report:

The template writes the boiler plate markup for a valid XHTML 1.0 file, with <html> and <head> tags and a little CSS styling. The variable $encoding contains an externally provided string with the character encoding for the output file (for example “UTF-8″). Likewise, variable $title provides the title for the report.

Next is the body of the report. The macro #writeElementHierarchy() recursively writes the nested list of model elements that serves as a “table of contents” of the report. We’ll look at its definition in a moment. Variable $report is an externally provided reference to our ReportFacade instance that holds the UML model. Method getRootElements() obtains a list of all model elements that have no owner. All other elements in the model are directly or indirectly owned by the model elements on this list.

After that, the templates goes into a foreach-loop over all element types in the meta model ($report.getTypes()). The body of the loop creates, for each element type, a list of all model elements for that type ($report.getElements()). For each model element, we write an <h2> tag with the type and name of the model element, and a named anchor to cross-reference model elements within the report using hyperlinks. The XMI IDs of the model elements serve as anchor names. The macros #writeAttributes(), #writeMetrics(), #writeSets(), and #writeRuleViolations then output the detailed information for each model element. So let’s have a look at those macros.

Write the element hierarchy

This is macro #writeElementHierarchy(), along with two little helper macros it requires:

The macro receives a list of model elements as input parameter. The list may be empty or null. The macro produces an unordered HTML list (<ul>) with the type and name for each model element, and a hyperlink to the detailed description of the model element (call to macro #writeElementRef()). If an element owns sub-elements, those elements are written out recursively in a nested, unordered list.

Macro #escp() replaces XML special characters (<, >, & etc) with their predefined entities. For simplicity, we use a little utility class of our own (ReportUtils, not shown here) for that. Velocity comes with an optional tools package (Velocity tools) that also provides this functionality and should be used instead in a production environment.

Write the attribute values

To generate a table with the values of all attributes of a model element, we define macro #writeAttributes() as shown below. It takes the model element to write as input parameter. The macro determines the type of the model element, obtains the list of the attributes for that type, and writes out an HTML table with the attribute names in the first column, and the attribute values in the second column.

Writing the attribute values requires a bit of attention. The SDMetrics meta model distinguishes between data and reference attributes. Data attributes carry string values, reference attributes contain references to other model elements. An attribute can be single-valued or multi-valued.
Multi-valued attributes contain a set of values, single-valued attributes just one. The nested #if-statements in macro #writeAttributes() determine which combination of data/reference and single/multi-valued attribute applies, and obtain the values accordingly. Helper macro #writeElementRefs() is used to generate a comma-separated list of hyperlinks for multi-valued reference attributes.

Write the metric values

Macro #writeMetrics() below creates the table with the metric values for a model element. The macro determines the list of metrics for the element type, and writes out an HTML table with the metric names in the first column, and the metric values in the second column. Metric values can be strings, numbers, or references to other model elements. Helper macro #writeValue() checks if a metric value is a model element reference or not, and either writes a hyperlink to the model element, or just the plain metric value.

Class com.sdmetrics.velocity.ReportLauncher has a main method that applies the template to the XMI file “sample.xmi” in the project’s root directory.

The support for report generation can be taken further. For example, it is easily possible to define metric or condition expressions directly in the template, have them evaluated on-the-fly by the metrics engine, and include the result in the report. I’ll demonstrate this in a future post.

In this post we’ll look at another real-life case study of how to adapt SDMetrics in order to solve a particular measurement problem. An SDMetrics user needed to count the OCL expressions in classes. SDMetrics does not produce this count out of the box, but needs a little tweaking. In the UML2, an OCL expression… [Continue reading]

SDMetrics V2.31 was released today. This is a maintenance release that addresses some issues with the XMI import. Automatic recognition of XMI 2.4/2.4.1 files Ever since XMI 1.0, the XMI standards mandated a “version” attribute in the root element of the XMI file to indicate the XMI version of the file. It was simple and… [Continue reading]

I found an interesting review paper titled “A Systematic Literature Review on the Quality of UML Models” by Marcela Genero, Ana Fernández-Saez, H. James Nelson, Geert Poels, and Mario Piattini. It was published in the Journal of Database Management 22 (3), 46-70, 2011. You can also find it here. The paper aims to determine the… [Continue reading]

SDMetrics advertizes itself as “The Software Design Metrics tool for the UML”. SDMetrics has a flexible XMI parser to import UML models, as XMI is the most common UML model interchange format. But XMI is not limited to UML model interchange. It can be used to serialize any MOF-based models to XML. Therefore, SDMetrics too… [Continue reading]

Recently, some SDMetrics Open Core users approached me with a neat little measurement problem that is ideally suited for this blog. They used Enterprise Architect to create UML 1.3 component diagrams with classifier roles. The XMI output of Enterprise Architect for these diagrams contained several tagged values for the classifier role instances, including two with… [Continue reading]

The January 2013 issue of “Software & Systems Modeling” contains a new empirical study on UML quality modeling. The paper is titled “Effects of stability on model composition effort: an exploratory study ” by Kleinner Farias, Alessandro Garcia, and Carlos Lucena. The full paper is available for download. Here is my review. The paper investigates… [Continue reading]

In a previous post, we have defined a basic set of size and complexity metrics for UML sequence diagrams with SDMetrics. Today, we’ll add a few more sequence diagram metrics that are potentially useful to identify design flaws. I will show how to implement these metrics using the SDMetricsML. 1. Number of “self” messages The… [Continue reading]

SDMetric v1.0 was released on December 1st 2002, 10 years ago on this very day. This calls for immediate celebration! And what better way is there to celebrate than with a bunch of software quality related statistics? So, here we go: SDMetrics Number of major releases: 8 Number of minor releases: 4 Size of first… [Continue reading]

SDMetrics is primarily a UML design quality measurement solution. It contains an XMI parser to read UML models from XMI files. The XMI parser has attracted some interest on its own. In this post, I’ll talk a bit about the reasoning behind the design decisions of the XMI parser, and discuss the consequences for practical… [Continue reading]