• Prepare a new actifsource Project as seen in the Actifsource Tutorial Simple Service

  • Setup the Target Folder src
  • Create a Generic Domain Model
  • Create a Specific Domain Model
  • Create a Code Template

• Use any package structure. For Example

• To share a project you have to setup a VCS (Version Control System) first

• You may choose one of the following

  • GIT: https://git-scm.com/
  • SVN: https://subversion.apache.org/

• To enable the Eclipse Team Support, you have to install an Eclipse Team Provider

• If you are using SVN, you may choose one of the following

  • Subversive: http://www.eclipse.org/subversive/
  • Subclipse: http://subclipse.tigris.org/

Share Project

• Share your Project via the context menu Team on your project

• The shared project shows revisions and icon overlays

Part III Local History

• The Local History is part of the Eclipse Team Support

Local History

• Change any of your Resources
• Save the Resource

• The '>' in the Resource Navigator indicates, that the Resource has been changed
• From the context menu of Patient choose Team/Show Local History…

• Select two of the shown versions of your interest
• From the context menu, select Compare with Each Other

• The actifsource Resource Compare Editor will show you any changes between the selected versions

• Working in a team may lead to conflicts if more than one developer changes the same resource at the same time
• The Resource Compare Editor helps to resolve these conflicts

Edit Conflicts

• In the meantime, another developer (Developer 2) added a new Call DeleteEverything to the Service Patient
• As we have added the Call DeleteAll in the same resource before, there will be a conflict when updating from the repository
• To simulate another developer, just check out your project on a different location
• Modify the resource as shown above
• Check in the modified resource to your repository

- Back to Developer

• Before checking in our modification (Call DeleteAll to the Service Patient) let's check for updates
• From the context menu of your project, select Team/Update

• As expected, a conflict occurs

• From the context menu of the conflicting resource Patient select Team/Edit Conflicts…

• The actifsource Resource Compare Editor will show you the changes
• Your local version on the left
• The repository version on the right
• Use the marked tools to copy changes from one version to the other

• Once resolved all conflicts, choose Team/Mark as Merged from the context menu

• From the context menu, select Team/Commit to commit the actual work to your repository

• Prepare a new actifsource Project as seen in the Actifsource Tutorial Simple Service

  • Setup the Target Folder src

• Create a new Class named “Project” in the package ch.actifsource.tutorial.project.generator.spec using the New Resource Wizard

• Create a new Template named “ProjectSettingsTemplate” by right clicking the newly created class Project and selecting the New Template Wizard.
• Since you clicked on the resource Project actifsource automatically fills in the base type, meaning the template is executed for each instance of the class Project

• Write the content of the .project file or copy it from one of your existing eclipse project.
• Replace the variable information by linking to the actifsource model (Use Content Assist: Ctrl+Space).
• Use the project name to create a subdirectory for each project in the target folder.
• In this example we only generate the project name from the model, feel free to extend the model to fit your needs.

• Sometimes you may have configuration files equal for all projects, in this case just put them into a folder in the generator project.
• Create a “src_common” folder and copy the .asproject and the .classpath file of a preconfigured project into it or use the ones on the following page.

• Now after you generated and copied all project files, like the .project, .classpath and .asproject, you need to generate a .projectconfig file.
• You need to create a .projectconfig file for each project. The .projectconfig defines the eclipse name of the project and the initial file structure. Since all settings are stored inside the projects file structure as setting-files, this also defines the initial project setup.

• Write a template for the .projectconfig file, as before use the projectname from the model.

• Actifsource provides the following elements inside the project-element.

  • dir with attribute name to create a directory in project root
  • file with attribute src and dst to copy a file from the generator project to the generated project use the overwrite attribute to specify if the file is overwritten each time generator runs again
  • workingset with attribute name to add the project to a specific

• Create a BuildConfig named “ProjectBuild” using the New BuildConfig Wizard and including all templates.

• Create a new package ch.actifsource.tutorial.project.generator.usage.

• Create an instance of the Project class in the package ch.actifsource.tutorial.project.generator.usage named “TestProject”.
• This step will result in the first try to generate the project, but fails due to missing the buildconfig setup.

• Right click on the project and select properties
• Click on the category actifsource
• Goto the target folder tab and click on the src-folder
• Add the buildconfig ProjectBuild
• Add the package ch.actifsource.tutorial.project.generator.usage
• Now actifsource will generate the xml files with current xml-comment and the project builder creates a new project.

• As you have seen generating projects is very similar to generating any other file, except that you have to generate the project type specific settings files and a project configuration file.
• Depending on your needs you may define the builders listed in .project files or the required libraries listed in .classpath files based on your models information.

• 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:

• Prepare a new actifsource Project as seen in the Actifsource Tutorial Statemachine
• Create a generic Domain Model as shown above
• State.transition 🡪 Decorating Relation with Decorator State.-state.event
• Transition.targetState 🡪 Use Relation with RangeRestriction Transistion.-transition.-state.state

• Create a user defined diagram type to display and edit domain specific diagrams

Create a Diagram Type

• Create a new DiagramType named Statemachine in the Package generic

• The Root Class defines the Resource which contains the elements that shall be managed on your domain diagram

• Select Statemachine as Root Class

• The Allowed Class defines all the Resources which shall be managed on your domain diagram

• Select State as Allowed Class since we want to design a state machine

• Allowed Classes might be created using the domain diagram editor via a Palette Tool

  • HidePaletteEntry: No Palette Entry to create this Allowed Class
  • ShowPaletteEntry: Palette Entry named as the Allowed Class
  • ShowRenamedPaletteEntry: Palette Entry named as defined

• Select the PaletteEntry ShowPaletteEntry or ShowRenamedPaletteEntry

• Allowed Relations are relations that shall be displayed on the domain diagram

  • AllowedDependencyRelation: Dotted Line that shows dependencies between components
  • AllowedDirectRelation: Direct relation between resources A and B
  • AllowedIndirectRelation: Indirect relation between resources A and B via X

• We like to see a transition from state to state just as a simple arrow

• Define the Selector State.transition.targetState for the Indirect Relation

• Define openEditor as false if you do not want to open the Resource Editor automatically after creating the transition via domain diagram editor.

• Create a domain diagram based on the diagram type to edit the underlying root resource

• Create a new Statemachine named Statemachine1 in the Package specific

• We could now define Event, State and Transition using the Resource Editor
• Let’s now try the Domain Diagram Editor

• Create a new Domain Diagram named Statemachine1 for the Statemachine Statemachine1 in the Package specific
• Use the context menu directly on the Statemachine Statemachine1

• The domain diagram shall be named Statemachine1
• DiagramType is detected automatically based on the Root Resource
• Single Root is filled in automatically based on the context of new Domain Diagram

• Create new States named Open Close Opening and Closing using the State Tool from the Palette

• Start adding Transitions using the Relation Tool from the Palette

• Therefore you are asked for an Event when creating a new Transition
• Create a new Event called Command_Close using Content Assist (or choose an existing Event

• The Event Command_Close has been created
• The Transition based on the Event Command_Close with targetState Closing has been created

• Add some more Transitions based on the new Events Command_Open Sensor_Closed Sensor_Opened

• Add two more Transitions based on the existing Events Command_Close and Command_Open
• Use Context Assist to choose the existing Events

• Define a highlight path from node to node over any edge

• Let’s see where transitions are leading to from source to target state
• Define a HighlightPath for the Allowed Class State as shown in the example above

• Hoover your cursor on any State to activate the HighlightPath from State via Transition to TargetState

• Define a tooltip for elements on the domain diagram

• Create a new FunctionSpace named Tooltip in the Package generic

• Create a new ResourceInfo with typeRef State
• Create a new TemplateFunction named tooltip

• Open the Template Editor by double clicking Tooltip.State.tooltip in the Project Explorer

• Print the State.name
• For every Transition in State: Print Transition.event.name
• For every Transition in State: Print Transition.targetState.name

• Use the TemplateFunction tooltip@Tooltip by using a SelectorTooltip in the Diagram Type

• Hoover your cursor on any State to activate the Tooltip

• Prepare a new actifsource Project named ch.actifsource.tutorial.diagramm.ports as seen in the Actifsource Tutorial Simple Service
• Use the following package structure

• Create a ClassDiagram named Design in the Package generic using the DiagramEditor

• Create the following Classes

  • System Process Port Port_Out

• Insert an Composition between

  • System and Process

  • Process and Port_In

  • Process and Port_Out

• Insert a Association between

  • Port_Out and Port_In

• Adjust the Cardinalities as shown above

• Create a new Resource of type System in the package ch.actifsource.tutorial.diagramm.ports.specific (Right-click on the package and choose New->Resource from the menu)

• Give the name SystemA to the the newly created resource in the New Resource Wizard

We create a new Diagram Type called System in order to define properties of Domain Diagrams of Systems:

• Select the resource System in the package ch.actifsource.tutorial.diagramm.ports.generic and choose New -> Diagram Type from the menu

Define a new Diagram Type

• Enter SystemDiagram as name for the newly created DiagramType in the New DiagramType Wizard

• Make sure that ch.actifsource.tutorial.diagramm.ports.generic.System has (automatically) been chosen as RootClass

We create a new Domain Diagram for the resource SystemA

• Select the resource SystemA and choose New ->Domain Diagram from the menu

• Enter SystemA as the name of the new diagram in the New Domain Diagram Wizard

• Click Finish

Next, we create a shape and a figure for the class Process in order to define how elements of type Process are displayed and handled in the Diagram Editor:

• Open SystemDiagram in the Resource Editor

• Create a statement allowedClass refering to an AllowedClass with class ch.actifsource.tutorial.diagramm.ports.generic.Process

• As paletteEntry choose the type ShowPaletteEntry

• Create a new ClassStyle as style and add a new ModelShape as shape to it

• Choose ProcessShape as name of the new ModelShape

• Create a statement figure that refers to a new ch.actifsource.ui.diagram.figure.CompactFigure

• Choose ProcessFigure as name of the new CompactFigure

• Create a new drawElement and choose the type DrawRectangle from the Type Selection dialog

• Define a fillColor by choosing DarkGray with the help of the Content Assist

• Create a position (x=0, y=0) and a size (width = 100%, height=100%) statement as shown above

We define a childContainer for the ProcessShape

• Create a ChildContainer
• In the newly created ChildContainer define a Point as position with x = 0% and y = 20% (the container should not cover the uppermost rectangular section of the shape)
• Define a Size with width=100% and height=100%

We define the label of a process shape to be the name of the corresponding Process choose the initialization properties of a process shape and define a minimum size of process shapes:

• Create a labelSelector of type FigureEditableLabelSelector (this allows us to edit the name of a Process directly from the Diagram Editor)
• Create a minShapeSize with width = 100 and height = 100 (size in Pixels)
• Create a ShapeInitialization and change its show Part not hide its parts when newly created

We create two Process instances, ProcessA and ProcessB in the Domain Diagram Editor:

• Open the DomainDiagram SystemA in the Diagram Editor
• Select Process from the Palette
• Left-Click in the diagram to open the New Resource Wizard and choose ProcessA as the name of the new Process resource
• Repeat the previous step and choose ProcessB as the name of the second resource

Check and inspect the newly created resources:

• Check that Ctrl+Click on the label of a Process opens the corresponding process in the Resource Editor
• Choose Edit from the Palette and edit the name of a process shape by left-clicking on its label.

Next, we define a shape and figure for Port_Ins:

• Add a new AllowedClass with class Port_In and define a palleteEntry of type ShowPaletteEntry
• Add a statement style and then create a new shape statement refering to a new ModelShape
• Give the name PortInShape to the new resource

• Create a figure of type CompactFigure with the name PortInFigure

• Add a drawElement of type DrawArc to the PortInFigure
• Define the fillColor as White and the lineColor as Black
• Create a position with x=60% and y=0%
• Create a statement size refering to a resource of type Size with width=40% and height=90%
• Define an offset with startArc=90 and endArc=180 (degrees)

• Add a second drawElement of type DrawLine to the PortInFigure
• Create a startPosition with x=30% and y=50%
• Create an endPosition with x=60% and y=50%

• Add a third drawElement of type DrawRecangle to the PortInFigure
• Create a statement position and set x=0% and y=0%
• Create a statement size and set width=40% and height=100%

• Open SystemDiagram in the Resource Editor
• Create a new AllowedClass that refers to the class Port_Out
• Create a new ClassStyle that refers to a new ModelShape. Give the name PortOutShape to the newly created ModelShape.

• Add a CompactFigure with the name PortOutFigure to PortOutShape as shown above

• Add a drawElement of type DrawRecangle to the PortOutFigure
• Create a statement position and set x=0% and y=0%
• Create a statement size and set width=40% and height=100%

• Add a second drawElement of type DrawLine to the PortInFigure
• Create a startPosition with x=30% and y=50%
• Create an endPosition with x=60% and y=50%

• Add a second drawElement of type DrawLine to the PortInFigure
• Create a startPosition with x=30% and y=50%
• Create an endPosition with x=60% and y=50%

• Add a third drawElement of type DrawOval to the PortOutFigure
• Define the fillColor as White and the lineColor as Black
• Define the position with x=60% and y=0%
• Define the size with width=40% and height=100%

We define the position of ports relative to their process shapes and their behavior:

• Create a MovablePortShape in the ProcessShape

• Define an anchorPoint with x=20% and y=0%

• Define a movableRange with a position with x=0% and y=0% and a size with width=100% and height=100% (meaning that a port can be moved to any point on the boundary of the rectangular process shape)

• We do not define an orientation (the shape of a port is thus rotated when moved along the boundary of its parent shape)

We define a selector for all the allowed Port figures:

• Open the SystemDiagram in the Resource Editor and create a ChildFigureSelector as Decorator for portFigureSelector[Port]
• Define the selector Process.port_In union Process.port_Out which selects all ports of type Port_In and Port_Out that belong to a Process

Next, we a PortIn and PortOut to each of our two Processes:

• Open the Domain Diagram SystemA in the Diagram Editor (Note: If the diagram is still open, close it first and then re-open it in order to update the behavior of the diagram)
• Choose Port_In from the Palette and left-click on ProcessA
• Choose the name in_a in the opened New Resource Wizard
• In the same way create a Port*In with name in_b for ProcessB
• Choose Port_Out from the Palette and left-click on ProcessA
• Choose the name out_a in the opened New Resource Wizard
• In the same way create a Port*In with name out_b for ProcessB

• Open the Domain Diagram SystemA in the Diagram Editor and position the newly created ports by selecting them and moving them on the boundary of their process shapes.

Finally, we want to be able to connect outgoing ports Port_Out to ingoing ports Por_In by the relation Port_Out.port_In

• Open the SystemDiagram in the Resource Editor
• In the allowedClass for Port_Out create an allowedRelation of type AllowedDirectRelation and define the selector Port_Out.port_In

We connect out_a with in_b as follows:

• Choose Relation from the Palette
• Click on the port out_a. Then drag the mouse to the port in_b and click on port in_b
• In the same way connect out_b to in_a
• Open and inspect the newly created statements by opening SystemA in the Resource Editor as well:

Next, we want the Process shape to change its color when its parts are hidden:

• Open ProcessFigure in the Resource Editor and add a third drawElement of type DrawRectangle and define the properties size and position as above (Note that you can also simply copy and paste the existing DrawRectangle).
• Define the fillColor as ActifsourceForeground
• Create a condition by using the Content Assist and choosing ShowContainerCondition (i.e., the shape should have the color ActifsourceForeground when its container is not hidden)

Add conditions to figures

• Add a condition HideContainerCondition to the first drawElement of type DrawRectangle of the ProcessFigure (thus, the shape will be DarkGray when its container is hidden).

• Open the Domain Diagram SystemA in the Diagram Editor and righ-click on one of the Process shapes
• Select Show/Hide Resource Part color of the shape changes accordingly

• Open the SystemDiagram in the Resource Editor
• Create a TypeStyle
• Create a NoteStyle for the new TypeStyle
• Choose NoteClipFigure as figure
• Define a labelSelector of type FigureEditableLabelSelector and add the placementSelector NoteItem:NoteItem and the propertySelector NoteItem.nodeText

• Open the Domain Diagram SystemA in the Diagram Editor
• Select New Note from the Palette
• Right-click on the shape ProcessB to place the note

• Select Edit from the Palette
• Right-click on the note and edit the text
• Write a note (such as This shape represents ProcessB)

We add a search function to our Domain Diagrams that allows us to search for all Processes

• Open SystemDiagram in the Resource Editor
• Create a SearchPath in the AllowedClass for class Process and define the selector Process:Process as path

• Close and re-open the Domain Diagram SystemA in the Diagram Editor
• Open the Content Assist in the search field and select ProcessA from the proposals

Finally, we want to display the name of a port as label in the Domain Diagram Editor:

• Open PortOutShape in the Resource Editor
• Use the Content Assist to add a borderShape statement that refers to NameBorderShape

• Open SystemDiagram in the Resource Editor
• Add a FigureLabelSelector with the selector Port_Out.name as Decorator to labelSelector

• Open SystemA in the Diagram Editor
• Check that the name of outgoing ports are now displayed as labels next to their ports
• Try to move and re-position the labels (in the Select Mode)

• We want to specify the behavior of our coummicating processes: ProcessA should be a simple coin machine that is connected to a dispenser ProcessB
• We create an UML State Machine that defines the behavior of ProcessA and link the state machine to our Domain Diagram

First, we make all (built-in) resources needed to build UML diagrams available in our project:

• Right-click on the project ch.actifsource.tutorial.diagramm.ports and choose Properties from the menu
• Select actifsource in the opened Properties dialog and click on Add Builtin
• Select UML from the opened built-in dependency Selection dialog and close both dialogs by clicking OK

We create a ch.actifsource.solution.uml.statediagram.generic.simple.Statemachine called ProcessA_State_Machine as described in Actifsource Tutorial – UML Statemachine in the package ch.actifsource.tutorial.diagramm.ports.specific.

We add a reference to an UML state machine (that describes the behavior of the Process) to Process

• Open Process in the Resource Editor
• Add a UseRelation called statemachine to Process
• Define the range of the relation as ch.actifsource.solution.uml.statediagram.generic.simple.Statemachine

• Open SystemA in the Resource Editor
• Create a statemachine statement that referers to ProcessA_State_Machine to ProcessA

We define an action that is triggered by double-clicking on a process shape in our Domain Diagram and opens the UML state machine associated with the corresponding Process

• Open SystemDiagram in the Resource Editor
• With the help of the Content Assist, add an OpenDiagram_DoubleClickAction to the AllowedClass for the class Process
• Create a DiagramSelectorActionProperty as Decorator for shapeActionProperty and define the selector Process.statemachine.stateDiagram (i.e., the action should open the selected diagram)

• Open the Domain Diagram SystemA in the Diagram Editor
• Double-Click on ProcessA and make sure that the diagram ProcessA_State_Machine is automatically opened in the Diagram Editor

Setup a project ch.actifsource.tutorial.statemachine.code with a meta-model for Statemachine create two instances of Statemachine and implement a code template for Statemachine as seen in the Actifsource Tutorial State Machine:

• Prepare a new Actifsource Project ch.actifsource.tutorial.statemachine.code
• Create a meta-model for Statemachine
• Create two instances of type Statemachine namely Statemachine1 and Statemachine2
• Write a code template StatemachineImpl for the type Statemachine
• Use the package structure shown above

First, we import all the resources needed to enable the support of Code Snippets in our project:

• Select the project ch.actifsource.tutorial.statemachine.code and choose Project->Properties from the main menu
• In the properties dialog choose Actifsource and go the Built-in Dependencies tab
• Click on Add Builtin
• In the dialog Select a built-in dependency choose CODESNIPPET and click on OK

• Close the Properties dialog by clicking on OK

We add a Code Snippet relation to class Transition:

• Open the class Transition in the Resource Editor
• Add a (third) property to the class
• Choose StructuredCodeSnippetRelation in the dialog Type Selection

• Insert condition as name of the relation
• Create a new CodeSnippetRelationAspect as shown above
• Choose Cardinality0_1 as subjectCardinality and as objectCardinality
• Create a new language statement by calling the Content Assist and choosing CMinusCondition

We add a new Composition called variable to the class Statemachine:

• Open Transition in the ResourceEditor
• Add a new property and choose Composition in the Type Selection dialog
• Insert variable as the name of the relation
• Choose new ch.actifsource.core.Class as the range with the support of the Content Assist

• Insert Variable as name of the newly created class, which is opened automatically in the Resource Editor

A conditional expression for a Transition should be able to use all Variables that are owned by the Statemachine of the Transition as variables:

• Insert a RelationTokenProvider
• Define the Selector Transition.-transition.-state.counter which selects all Variables that are owned by the Statemachine of the Transition
• Choose ch.actifsource.codesnippet.metamodel.TokenType.Variable as tokenType

We add a condition to the state transition triggered by the event start that restricts the number of times the Statemachine can switch to the State Started

• Open the instance Statemachine1 in the ResourceEditor
• Add two statements for variable to Statemachine1
• Choose startCounter as the name of the first and startLimit as the name of the second Variable

We add a conditional expression to the state transition triggered by the Event start in the State Initialized

• Open the state Initialized in the Resource Editor and then open its Transition start
• Open the Code Snippet Editor by selecting the relation condition and pressing Enter
• Call the Content Assist in the Code Snippet Editor and choose startCounter
• Enter ' < ' in the Code Snippet Editor and call the Content Assist again
• Choose startLimit in the Content Assist

We enforce that the Statemachine can only switch a maximum of startLimit times to the State Started by adding the same conditional expression also to the Transition triggered by the Event start in the State Stopped

• Enter the conditional expression in the same way as on the previous page

We create a new Diagram Type called Statemachine in order to define properties of Domain Diagrams of Statemachines:

• Select the package ch.actifsource.tutorial.statemachine.code.generic and choose New -> Diagram Type

• Enter Statemachine as name for the newly created DiagramType in the New DiagramType Wizard
• Choose ch.actifsource.tutorial.statemachine.code.generic.Statemachine as RootClass

• Define allowedClass as ch.actifsource.tutorial.statemachine.code.generic.State
• Choose ShowPaletteEntry as paletteEntry
• Insert an allowedRelation of type AllowedIndirectRelation with selector State.transition.targetState

Now we create a new Domain Diagram for Statemachine1 based on the newly created Diagram Type:

• Select ch.actifsource.tutorial.statemachine.code.specific and choose New -> Domain Diagram

• Check the chosen settings in the open dialog and click Finish

• Choose Select in the Palette of the Diagram Editor and arrange the States such that all transitions are visible

Next, we will see how to display the conditional expressions associated with a Transition in the Domain Diagram. First, we create a function that generates the displayed text from the conditional expression:

• Select the package ch.actifsource.tutorial.statemachine.code.generic and choose New -> FunctionSpace

• Enter NameFunctions as name of the FunctionSpace

• Create a new FunctionContext with typeRef ch.actifsource.tutorial.statemachine.code.generic.Transition
• Create a new function in the FunctionContext and choose TemplateFunction in the Type Selection dialog

• Enter displayName as name of the TemplateFunction
• Open the TemplateFunction in the Template Function Editor by double-clicking on displayName in the Project Explorer

The function should display the name of the event triggering the Transition and in brackets the conditional expression if there is one:

• Enter Transition.event.name in the TemplateEditor followed by '[]'
• Place the cursor inside the brackets and choose Insert ColumnContext from the menu

• Choose Transition.condition as selector for the column context
• Enter CodeSnippet.displayCodeSnippetSingleLine@DisplayCodeSnippet in the column context. This function outputs a string that represents the expression in the Code Snippet as entered by the user, i.e., without parsing or processing it

We will use the newly created function displayName to define a NameAspect for Transitions

• Create a NameAspect with the Content Assist and choose TextSelectorAspectImplementation in the Select Decoration Type dialog

• Enter Transition.displayName@NameFunction as selector of the NameAspect, i.e., the name of the Transition will be the output of the function we have defined before

• Open the Statemachine1 Domain Diagram again and check that the Transitions are now displayed with their name including the conditional expressions as specified above

In this part, we will extend the template StatemachineImpl as implemented in the Actifsource Tutorial State Machine such that the statemachine executes a state transition only if the associated condition is fulfilled:

• Open the template StatemachineImpl in the Template Editor

We write an if-statement with the conditional expression associated with a Transition as condition:

• Insert a new Line Context and write the selector Transition.condition for the newly created context

• Write an if-statement in the new line context and insert a call to the function toC@CodeSnippetToCode on the CodeSnippet available in the this context as condition of the if-statement
• Add opening and closing braces around the existing assignment expression

• Open the generated files Statemachine1Impl.hpp (overwritten) and Statemachine2Impl.hpp (unchanged) and inspect the changes.

Part V Customized variable names

• The built-in template functions that we used so far generate the name of variables (and also functions) by calling simple name on the corresponding resource
• In this part we will change the generated variable names by adding a prefix to the variable names according to our naming convention

• Create a new Java source folder: select the project ch.actifsource.tutorial.statemachine.code and choose New -> Source Folder from the menu

• Insert aspects as name of the new folder

• Create a new package ch.actifsource.tutorial.statemachine.code.generic in the aspects folder: select the aspects folder and choose New -> Package from the menu

• Select the package ch.actifsource.tutorial.statemachine.code.generic in the folder aspects and choose New -> Interface from the menu
• Write IMyNameProvider as name of the new interface
• Choose ch.actifsource.codesnippet.metamodel.template.INameProvider as Extended interface

• Select the package ch.actifsource.tutorial.statemachine.code.generic in the folder aspects and choose New -> Class from the menu
• Write MyNameProviderLiteralAspect as name of the new class
• Choose ch.actifsource.core.model.aspects.impl.AbstractStatelessAspectImpl as Superclass
• Choose ch.actifsource.core.model.aspects.impl.IGenericLiteralAspect<IMyNameProvider> as Interface
• Click Finish

package ch.actifsource.tutorial.statemachine.code.generic;

import javax.annotation.CheckForNull;

import ch.actifsource.core.INode;
import ch.actifsource.core.Literal;
import ch.actifsource.core.job.IReadJobExecutor;
import ch.actifsource.core.model.aspects.impl.AbstractStatelessAspectImpl;
import ch.actifsource.core.model.aspects.impl.IGenericLiteralAspect;
import ch.actifsource.core.scope.IResourceScope;

public class MyNameProviderLiteralAspect extends AbstractStatelessAspectImpl implements IGenericLiteralAspect<IMyNameProvider> {

  @Override
  public boolean allowMultiline() {
    return false;
  }

  @Override
  public @CheckForNull String isValid(IReadJobExecutor executor, IResourceScope scope,
    String value) {
    return null;
  }

  @Override
  public Literal create(IMyNameProvider value) {
    return new Literal(value.toString());
  }

  @Override
  public @CheckForNull String getJavaConstructionExpression(IReadJobExecutor executor,
    IResourceScope scope, INode node) {
    return null;
  }

  @Override
  public @CheckForNull IMyNameProvider getValue(IReadJobExecutor executor,
    IResourceScope scope, INode node) {
    return null;
  }

  @Override
  public Class<IMyNameProvider> getValueType() {
    return IMyNameProvider.class;
  }

}

• In the newly created class remove all TODO comments
• Write the statement return MyNameProvider.class; in the method getValueType()
• Write the statement return new Literal(value.toString());

• Create a new Literal type: select the package ch.actifsource.tutorial.statemachine.code.generic in the folder asrc and choose New -> Resource from the menu
• Choose the type ch.actifsource.core.Literal as Type of the new Resource
• Write MyNameProviderLiteral as Name of the new Resource

• Open the new Literal in the Resource Editor
• Create a LiteralAspect with type JavaAspectImplementation and choose the class ch.actifsource.tutorial.statemachine.code.generic.MyNameProviderLiteralAspect as className
• Let the MyNameProviderLiteral extend ch.actifsource.codesnippet.metamodel.parsetree.template.NameProvider, which is the default NameProvider and generates names by calling simpleName@BuiltIn

• Create a new FunctionSpace Select the package ch.actifsource.tutorial.statemachine.code.generic in the asrc folder and choose New -> FunctionSpace
• Insert TokenNameFunctions as the name of the FunctionSpace and click Finish

• Let the new FunctionSpace TokenNameFunctions extend from TokenToName

• Open the FunctionSpace TokenNameFunctions in the Resource Editor
• Create a new FunctionContext with typeRef MyNameProviderLiteral
• Create a new function and choose TemplateLineFunction from the Type Selection dialog

• Insert variableName as the name of the new TemplateLineFunction
• Create a parameter Param of type ClassType and with classRef ch.actifsource.core.Resource
• Insert m_Resource.simpleName@BuiltIn as text, i.e., the function appends the prefix m_ to the output of Resource.simpleName@Builtin
• Warning: Please choose the exact function name for variableName or functionName since these functions are overwritten

• Create a new FunctionContext with typeRef Statemachine
• Create a new function and choose JavaFunction from the Type Selection dialog

• Insert generateNameProvider as name of the function
• Create a statement returnType of type LiteralType with literalRef MyNameProviderLiteral

    @Override
    public ch.actifsource.tutorial.statemachine.code.generic.IMyNameProvider generateNameProvider(final ch.actifsource.tutorial.statemachine.code.generic.javamodel.IStatemachine statemachine) {
      /* Begin Protected Region [[835774eb-ee6c-11ef-8f29-099ac721970d]] */
      return new IMyNameProvider() {};
      /* End Protected Region   [[835774eb-ee6c-11ef-8f29-099ac721970d]] */
    }

• Save the FunctionSpace TokenNameFunctions
• Open the newly generated file TokenNameFunctions.java in the Java Editor
• Write the statement return new IMyNameProvider(){} inside the protected region in the method body of the method generateNameProvider
• Save the file

• Open the template StatemachineImpl in the Template Editor
• Insert a new LineContext on the line after the case expressions
• Choose Transition.condition as the selector of the new context

• Insert a new LineContext on the same line
• Choose Statemachine.generateNameProvider@TokenNameFunctions:NameProvider as selector of the new context
• Write an if-statement with CodeSnippet.toCwithNameProvider@CodeSnippetToCode

• Insert a new line context on the same line and choose CodeSnippet:CodeSnippet (This dummy context allows Actifsource to correctly and automatically resolve the parameter to the function from the contexts)

• Save the template and make sure that the code is generated

• Open the file Statemachine1Impl.hpp and check that the variable names have been generated with the defined prefix "m_"

In this part, we will see how to add an action to a transition. We add the code corresponding to the action as a Code Snippet to the model. This code will be executed together with the transition:

• Open the class Transition in the Resource Editor and add a Code Snippet relation as already seen in Part II
• Insert action as name of the StructuredCodesnippetRelation choose subjectCardinality and objectCardinality Cardinality0_1
• Create a RelationTokenProvider with selector Transition.-transition.-state.variable and tokenType Variable
• Choose the language CMinus

We will now increment the startCounter each time that we switch to the State Started:

• Open Statemachine1 in the Resource Editor
• Add an action to the State Initialized and insert the code startCounter = startCounter + 1; into the Code Snippet Editor
• Add an action to the State Stopped and insert the code startCounter = startCounter + 1; into the Code Snippet Editor

• Open the template StatemachineImpl in the Template Editor
• Add a new line context after the assignment statement that updates the state
• Choose Transition.action as the selector of the state (to insert code for Transitions which have an action defined)
• Call the function toCwithNameProvider@CodeSnippetToCode on the CodeSnippet in the new line context

• Add a new line context on the same line as before and choose Statemachine.generateNameProvider@TokenNameFunctions:NameProvider as selector of the context
• Add another line context on the same line and choose the selector CodeSnippet:CodeSnippet (needed for the parameter matching)
• Save the template and make sure that the code in Statemachine1Impl.hpp is generated and overwritten

• Open the file Statemachine1Impl.hpp and check that the code that increments the counter has been correctly inserted
• Complete the generated classes by adding a member function initialize() and the missing variables (and probably adding the cases for the missing enumeration values to make the compiler happy).

• Create a new Actifsource project with the name ch.actifsource.tutorial.umlstatemachine

• Change to the tab Built-in Dependencies in the New Actifsource Project dialog

• Add the built-in dependency UML (which makes all resource needed to build and represent UML state machines available in our new project).

• Close both dialogs by clicking OK and Finish

• Create a new resource of type ch.actifsource.solution.uml.statediagram.generic.simple.Statemachine

• Enter CoinMachineStateMachine as the name of the new resource

Design an UML State Machine

• Open the state diagram of CoinMachineStateMachine StateDiagram_1, in the Domain Diagram Editor

First, we create two superstates, called NormalMode and DiagnosticMode:

• Select SuperState from the Palette and left-click in the Diagram Editor to create a superstate

• Enter NormalMode as the name of the new SuperState in the New Resource Wizard

• In the same way, create a SuperState called DiagnosticMode

• Select Start from the palette and right-click in the Diagram Editor to create a start state (i.e., the default or initial state of the state machine)

• In the Select mode, you can now re-size and re-position the states as usual in the Diagram Editor

• Select Relation from the Palette and insert a relation from the start state symbol to the superstate NormalMode

Now, we create nested states to define the behavior in the NormalMode

• Select State from the Palette and left-click in the lower section of the NormalMode state to create a nested state in the superstate NormalMode

• Enter the name Locked as name of the State in the New Resource Wizard

• In the same way create the two nested states Locked and Empty in the NormalMode and the two nested states TestLock and TestCoin in the superstate DiagnosticMode

• Select Start from the Palette and left-click in the lower section of the NormalMode state (see above) to create a default or start state

• As before, select Relation from the Palette and create a relation from the start state to the state Locked

• In the same way, create a start state in the DiagnosticMode and create a relation from this start state to the state TestLock

Next, we define the state transitions and events:

• Select Relation from the Palette and create a relation from the state Locked to the state Unlocked

• With Control+Click on the GUID of the newly created relation, you can now open the transition in the Resource Editor

• In the Resource Editor, create a new Event for the transition from state Locked to Unlocked

• Give the name Coin to the newly created event

• Switch to the open StateDiagram_1 in the Diagram Editor and check that the transition from Locked to Unlocked is now labeled 'Coin'

• In the same way, create the following transition and events: Unlocked Empty Empty TestCoin TestLock

We want to create a condition that is only true if the machine is non-empty. Thereto, we introduce a variable stockItems that keeps track of the number of items left in the machine:

• Open CoinMachineStateMachine the Resource Editor
• Add a PrivateVariableField to the CoinMachineStateMachine
• Create a VariableField with name stockItems and with type INTEGER as field

Next, we add guards to transitions such that the corresponding transitions only fire if the guard evaluates to TRUE:

• By Control+Click on the transition Unlocked open the transition in the resource editor
• Use the Content Assist to create a new ModelGuardImpl named hasStockItems as guard of the transition (see above)

• Add a GreaterExpression as booleanExpression to the ModelGuardImpl
• Create an operand1 of type VariableFieldExpression with a fieldRef with the VariableField stockItems as field
• Create an operand2 of type LiteralExpression with value
• Close the booleanExpression:

Next, we add actions that are executed together with transitions and introduce shared functions which can be used as actions by multiple transitions:

• Open CoinMachineStateMachine in the Resource Editor
• Create a new SharedFunction called lightOff as sharedFunction to CoinMachineStateMachine
• Create a new ManualFunctionImpl with viewName lightOff as functionImpl to the SharedFunction

• Add a transitionFunction of type ManualFunctionImpl to the transition Locked (see above)

• In the same way create the following transitionFunctions of type ManualFunctionImpl:

  • rejectCoin Empty
  • lightOn TestCoin

• Add a transitionFunction of type SharedFunctionRef to the transition TestLock which uses the sharedFunction lightOff

When the event Refilled occurs, the variable stockItems (i.e, the private variable that counts the number of stock items) should be set to the initial numbers of items:

• Add a transitionFunction of type ModelFunctionImpl to the transition Empty
• Add a statement of type Assignment to the ModelFunctionImpl
• Insert a fieldRef with field stockItems
• Add an operand of LiteralExpression with value INITIAL_STOCK_ITEMS

Each time the machine is unlocked, the number of stock items should be decremented by one:

• Create a new ModelFunctionImpl named decrementStockItems as entryFunction of the state Unlocked
• Add an Assignment as statement with an operand of type DecExpression
• Add an operand of type VariableFieldExpression to the DecExpression
• Add a fieldRef of type FieldRef to the VariableFieldExpression and use stockItems as field

• Open the StateDiagram_1 in the Diagram Editor and check that all the actions are displayed correctly as shown above

We add a transition that is triggered by an event Diagnose from the NormalMode to the DiagnosticMode (i.e., a technician should be able to switch to this diagnose state from any state in the normal mode). To save the state of the machine before switching modes, we introduce a history state:

• Add a history state by selecting History from the Palette
• Insert a transition triggered by a new event Return from the DiagnosticMode to the history state
• Create a transition triggered by a new event Diagnose from the NormalMode to the DiagnosticMode

Since the state of the DiagnosticMode is not saved before returning to the NormalMode, the light should be switched off when entering the diagnostic mode:

• Open the CoinMachineStateMachine in the Resource Editor
• Add an entryFunction of type SharedFunctionRef to the DiagnosticMode and use lightOff as the sharedFunction
• The entry function is now displayed when selecting the DiagnosticMode in the Diagram Editor (see above)

Finally, we want to generate code that implements the specified UML state machine:

• Right-click on the project ch.actifsource.tutorial.umlstatemachine in the Project Explorer and select Properties from the menu
• Select actifsource in the Properties dialog and go to the Target Folder tab
• Click on Add Target Folder, create a new folder called src, select this folder and click OK
• Select the folder src and click on Add BuildConfig and choose the build configuration StateDiagram_C from the dialog. Close both dialogs by clicking OK

• Open the folder src and make sure that the two files Statemachine_CoinMachineStateMachine.c and Statemachine_CoinMachineStateMachine.h have been generated and inspect the generated code
• If the two files have not been generated, check that the option Generate Automatically is active. If not, the code can also be generated manually as follows: right-click on the project in the Project Explorer and choose Generate Code from the menu.

• Install the graphviz tool from www.graphviz.org
• Make sure that graphviz is added to your system path
• The Actifsource meta model documentation generator is looking for the graphviz executable dot.exe in your system path.

• Create a simple meta model as shown in the Actifsource Tutorial Simple Service
• We recommend to make a new project for this tutorial ch.actifsource.tutorial.metamodel.docu
• Make sure to use a Class Diagram for the meta model design

Create your meta model

• Create a simple meta model as shown in the Actifsource Tutorial Simple Service
• Use a Class Diagram named Design

• Add proper comments to all classes, relations and attributes

• Add a Builtin Dependency to DOCUMENTATION_METAMODEL
• Add a target folder to generate the documentation

Prepare your project

• Open the properties of your project
• Add a Builtin Dependency to DOCUMENTATION_METAMODEL

• Open the properties of your project
• Add a new Target Folder docu
• Add the Build Config Documentation_MetaModel_html to the Target Folder
• Make sure you have added the Builtin Dependency to DOCUMENTATION_METAMODEL before

• Instantiate a new resource of type Documentation
• Add chapters and sub chapters to your documentation

Create the documentation model

• Select a resource folder
• Create a new resource of type Documentation using the new resource tool

Create a new resource named Service Documentation of type Documentation

• Open the resource Service Documentation
• Add some descriptions where needed
• Add a new Chapter named Service Design
• Make sure to refer to your Class Diagram named Design
• Save your resource

• Find the generated html documentation in the Target Folder docu