SDMetrics User Manual - Definition of Relation Matrices

SDMetrics - the UML design measurement tool

Contents > 8 Defining Custom Design Metrics and Rules > 8.4 Definition of Relation Matrices

8.4 Definition of Relation Matrices

The metric definition file also hosts the definition of SDMetrics' relation matrices (see Section 4.10 "The View 'Relation Matrices'"). The SDMetricsML defines a relation matrix with an XML element as follows:

<matrix name="matrixname" from_row_type="rowtype" to_col_type="columtype" 
        row_condition="..." col_condition="..." > 
  <description>Description of the matrix.</description>
  <'matrix definition' ...>
</matrix>

The attributes in the opening "matrix" tag are:

name (required): the name of the matrix, used in the dropdown list of the relation matrix view, and as filename when saving the relation matrix to files.
from_row_type (required): the type of the source elements that will make up the rows of the matrix (e.g., package, class, operation).
to_col_type (required): the type of target elements that will make up the columns of the matrix. This can be the same type as the row elements, or a different type.
row_condition (optional): a condition expression (see Section 8.5.4 "Condition Expressions") that must be true for a source element to be included in the matrix rows. If the attribute is not specified, all source elements will be included.
col_condition (optional): a condition expression that must be true for a target element to be included in the matrix columns. If the attribute is not specified, all target elements will be included.

Following the matrix tag is an optional description of the matrix, enclosed in <description> tags. The description is shown in the measurement catalog (see Section 4.13 "The View 'Catalog'"). Section 8.6 "Writing Descriptions" explains how to write descriptions for matrices.

The matrix definition is an XML element that defines the calculation procedure establishing the relationship from source elements to target elements in the matrix. The available procedures are the same ones that are available for set definitions (see Section 8.2 "Definition of Sets").

The definition below calculates a relation matrix showing UML abstractions for classes, i.e., which classes implement which interfaces:

<matrix name="UMLAbstr" from_row_type="class" to_col_type="interface">
  <description>UML abstractions: implementation of interfaces.</description> 
  <projection relation="client" target="abstraction" element="supplier" /> 
</matrix>

The evaluation procedure for this matrix definition is as follows. For a source element in a given matrix row, the projection is evaluated, as described in Section 8.2.1 "Projection". The number of occurrences of each target element in that projection is counted, and entered in the respective column of the relation matrix. This procedure is repeated for all rows of the matrix. Thus, we obtain in every table cell, a count of the number of relationship links from the source element to the target element.

In the context of a relation matrix definition, the set projection attribute recurse is not allowed.

As another example, assume we have defined, for a class, the set "AssEl_out" of elements associated with the class by bidirectional or navigable outgoing associations. We can then simply create a relation matrix showing these associations as follows:

<matrix name="ICAssoc_Cls" from_row_type="class" to_col_type="class">
  <description>Import coupling via associations between classes.</description> 
  <projection relset="AssEl_out" /> 
</matrix>

The evaluation procedure for this matrix definition is straightforward. For a source element in a given matrix row, the specified set expression "relset" is evaluated, as described in Section 8.2.1 "Projection". For each target element, the value of the respective column of the relation matrix is the cardinality of the target element in the set. This procedure is repeated for all rows of the matrix.

Continuing the association matrix example from above, we may want to reduce the size of the matrix by dropping empty rows (classes without outgoing associations), and empty columns (classes without incoming associations). Assume we have defined two helper metrics "Num_AssEl_out" and "Num_AssEl_in", to count for a class the number of outgoing and incoming associations, respectively. We add row and column conditions to the matrix definition as follows:

<matrix name="ICAssoc_Cls" from_row_type="class" to_col_type="class"
        row_condition="Num_AssEl_out>0" col_condition="Num_AssEl_in>0">
  <description>Import coupling via associations between classes.</description> 
  <projection relset="AssEl_out" /> 
</matrix>

Then, only classes with one ore more outgoing associations (Num_AssEl_out>0) will be included in the rows of the matrix, which eliminates empty rows. Likewise, the column condition Num_AssEl_in>0 eliminates empty columns.

Section 8.3.6 "Exempting Approved Rule Violations"

Contents

Section 8.5 "Expression Terms"