Diagram with Graphviz

• Setup the Graphviz software.
• Set Built-in Dependencies of an actifsource Project for graph generation.

Setup Graphviz

• Before you can generate UML diagram, you need a running environment of Graphviz. If you already have the Graphviz commands working from command line (with the PATH environment variable set), you can skip the following setup and proceed with the actifsource Project settings.

• Graphviz is an open source graph visualization software. Previously developed by AT&T it is now available under Eclipse Public Licence.

• Start your internet browser and open the address www.graphviz.org.

• Goto “Download” and check the licence agreement (Eclipse Public Licence).

• Select the executable package provided for your operating system, download the current release and run it.

• Follow the steps of the installation routine.

• Add the “bin” folder of the installation path (e.g. C:\\Program Files\\Graphviz\\bin) to your PATH environment variable.

Create a Project

• Prepare a new actifsource Project named ch.actifsource.tutorial.graphviz as seen in the Actifsource Tutorial Simple Service

  • Setup the Target Folder graph

• Use the this package structure

• There is an optional Built-in for Graphviz providing a build task that compiles the generated graphviz files into SVG graphics.
• Open the Project Properties.
• Select the actifsource Settings.
• On the tab “Built-in Dependencies” add GRAPHVIZ.

• We need a metamodel that provides those features we want to get displayed on our UML Class Diagram.
• The generated diagram will depend only on this model. So, in order to create a Class Diagram that displays the same classes as the generated code, we will have to write a template that generates for every class in the code a class in the Class Diagram.

Create a UML MetaModel

• Create a ClassDiagram named Metamodel.
• Add a new **Class**es for Class Method Attribute Association and Cardinality
• Add a new Enum Visibility

• Ctrl+ Left-Click on Cardinality to edit Cardinality in the Resource Editor.
• Add to IntegerLiteral-**Attribute**s named min and max
• Set the (subject-)Cardinality of both attributes to 0..1.
• Change the supertype extends from NamedResource to Resource, since cardinalities are identified by their minimum and maximum and not by a name.

• Ctrl+ Left-Click on the Enum Visibility to edit Visibility in the Resource Editor.
• Add the value public protected private and package to this Enum.

• Add a Aggregation extends from Class to itself.
• Add a Composition from Class to Association
• Add a Aggregation target back from Association to Class
• Set the (subject-)cardinality of target to exactly 1.
• Add **Composition**s from Class to Method and Class to Attribute
• Add a Relation from Association to Cardinality let it be an Composition for simplicity sake.
• Add a Aggregation from Attribute to Visibility and from Method to Visibility
• Set the (subject-)cardinality of the 3 Relations to 0..1.

Create a UML Meta

• Now let us create a Class Model package ch.actifsource.tutorial.graphviz.specific that shows the features we want to look at.
• For instance, create a Class Vehicle
• Create Subclasses Car Bicycle and Airplane i.e. Class having the extends-Relation set to Vehicle
• Create Classe Sedan Convertible SUV as Subclasses of Car
• Create a Class Wheel and a Class Wing
• Add an Association wheels to both Car and also to Bicycle and set the corresponding target to Wheel.
• Add an Association wings to Airplane which points to Wing

• We will generate graph definitions in the Graphviz DOT language and then in layout the graph to define our UML Class Diagram using the Graphviz DOT command. You can find the documentation of the DOT language on the Graphviz homepage.
• Graphviz provides several output formats: raster graphics like PNG, or vector graphics like PostScript or SVG.
  We will prefer SVG as output format since it can easily be post-processed, and the graphics can be embedded in HTML Pages and contain tooltips and hyperlinks.

Create a build configuration

• Select the package ch.actifsource.tutorial.graphviz.template.
• Create a new BuildConfig and name it Diagram

• Create a new Template named ClassDiagram
• The Template ClassDiagram is now placed into the selected BuildConfig Diagram

• Select the ClassDiagram TemplateGeneratorTask.
• Insert after the selection a GraphvizBuildTask with Ctrl+Enter.
• The GraphvizBuildTask will effect that every File with File Extension .dot in the Target Folder and its subdirectories is processed with the Graphviz DOT command and an SVG File with the same name but File Extension .svg is written.

Create a graph template

• If you are interested in the full capabilities of Graphviz, consult the documentation on www.graphviz.org.

• Open the ClassDiagram Template with the Template Editor.

• Create a directed graph (digraph) with the following attributes:

  • Default rankdir (i.e. rankdir=TB: top-bottom), so unconnected nodes (i.e. Class will appear on top.
  • ordering=out: Preserve the order of the outgoing edges (i.e. left sibling before right sibling, etc.)
  • nodesep=0.5; ranksep=0.5: Space among nodes of same rank, Space between ranks
  • splines=spline: Draw the edges (i.e. Association and extends as cubic splines.

• Place nothing in it but a single cluster, that will be drawn with a frame around

  • Label this cluster Class Diagram.

• The main elements of a DOT file are graph, node and edge.

  • graph Definition: graph GraphID { … }
  • node Definition: NodeID [attr~1~=value~1~, … , attr~n~=value~n~];
  • edge Definition: NodeID~tail~ -> NodeID~head~ [attr~1~=value~1~, … , attr~n~=value~n~];

• The default values of the attributes can be set with special statements:

  • node [attr~1~=value~1~, … , attr~n~=value~n~];
  • edge [attr~1~=value~1~, … , attr~n~=value~n~];

• Set the default attributes for Class Set its node shape to record and set fill color to lightyellow.

• Set the default attributes for the extends Relation: The arrow should point from bottom to top (dir=back) and have an empty arrow head.

• Set the default attributes for the Association The arrow head should have a V-shape (vee).

Declare Classes, Subtype relations and Associations

• Let us now insert line contexts for the UML artifacts we discussed before:
• Add a line context for all Class
• Be sure you choose ch.actifsource.tutorial.graphviz.generic.Class and not ch.actifsource.core.Class
• Add a line context for all Class with a nested line context which iterates over Class.extends
• The Class of the outer (hidden) context is named in the template editor with Class[2], the Class of the inner context (so the base class) is named with Class.
• Add an edge statement back from Class to Class[2].
• Add a line context for all Class with a nested line context for all Association
• Add an edge statement from Class to the Association.target labeled with the Association.name

Add Methods and Attributes

• We want to subdivide the class nodes to display the methods and attributes. For this feature, it will help we did not choose a simple rect shape for class nodes, but a record shape: With pipe characters “|” we can subdivide node shapes and with curly brackets “{” and “}” swap the direction of division from left-right to top-bottom and vice versa.

• Change the label of the class node, so the node is partitioned vertically into 3 fields with the Class.name in the first field, all fields left-justified.
• It is not possible to have column contexts nested.
• Therefore split the label into three lines using the backslash “\” at the line end.
• Add line contexts to iterate over the Method of a Class and over the Attributes of a Class

Add Visibility to Methods and Attributes

• We need the visibility symbols in our model in order to display it in the graph. Or, we need a Java function (see Actifsource Tutorial Complex Service) that maps the Visibility elements in the model onto the UML symbols.
• Open the Enum Visibility in the Resource Editor.
• Add a StringLiteral Property umlSymbol with (subject-)cardinality exactly 1.
• Set the umlSymbol of the enumeration values to the respective UML symbols: +, #, -, ~.

• In the template, insert a new Column Context in the Context which iterates over all Method

• Select in this Context the Method.visibility

• In this context Insert Visibility.umlSymbol

• Repeat the 3 steps for Attribute.visibility

• You can eliminate the empty record fields in the class nodes of the graph by checking if there are any methods or attributes:

• Add a Line Context inside the context which iterates over all Class
• Set the Selector to Class.method union Class.attribute
• This will iterate over the set union of the Elements in Class.method and those in Class.attribute
• Choose First (Alt + 1), so that this Context is entered at most once.
• Add a line that generates only a simple rect for a Class
• Choose Empty (Alt + 5), so that this line is evaluated if the Context “Class.method union Class.attribute is empty.

Add Cardinality

• We did not cover cardinalities so far.

• Add a Line Context that selects the Association Cardinality

• In this Context, add a headlabel, that contains the min and max Cardinality:

  • In the label insert a Column Context for Cardinality.min and one for Cardinality.max
  • For empty Cardinality.min context (Alt + 5), insert 0.
  • For empty Cardinality.max context (Alt + 5), insert *.

Distinguish Association types

• In UML, associations are marked with a diamond, if they are aggregations or compositions.
• Add the Class: Aggregation and Composition which are subclasses of Association
• Edit the typeOf Property of the **Relation**s wheels and wings and replace Association by Aggregation and Composition respectively.

• Add a Line Context

• In the Selector, cast Association to Aggregation and Composition respectively. The Line Contexts will be entered then only if it os an Aggregation or Composition

• Set the arrowhead attribute to diamond and to ediamond (=empty diamond).

UML Class Diagram

• The resulting graph will look now similar to this one: