• Download Java from www.oracle.com.We recommend installing at least version 17. Alternatively, you can use OpenJDK.You can also skip this step if you optionally download the JRE via the Eclipse installer
• Install Java on your desktop computer
• Start by downloading Eclipse Installer from www.eclipse.org/downloads
• Now go to File Explorer and click on Downloads after that click on the eclipse-inst-jre-win64.exe file for installing Eclipse IDE.
• Select the installation version “Eclipse IDE for Eclipse Committers”

• Actifsource is realized as an Eclipse Plugin

• For more information about eclipse see also wikipedia (Eclipse (software))

  

• From the menu Help select Install New Software...

  

• Click Add...

• Enter Name: actifsource

• Enter Location: https://www.actifsource.com/updates or the given update site

• Click OK

• Select actifsource
• Click Next

• Click Next

• Carefully read the license agreement
• If you agree, select I accept the terms of the license agreement
• Click Finish

• Click Yes to restart Eclipse

• In the Eclipse Platform a Perspective determines the visible actions and views within a window
• See also Using Perspectives in the Eclipse UI

• Click on the Open Perspective tool in the Eclipse toolbar
• Click Other...

• Select the actifsource perspective
• Click OK

↪ Install Actifsource as a plugin from www.actifsource.com/
↪ Open the actifsource Perspective

↪ In the Open Perspective dialog click on Actifsource
↪ Click OK to confirm.

ⓘ Make sure the actifsource Perspective is activated

↪ Create a new actifsource Project

↪ Choose the project’s name com.actifsource.simpleservice
↪ Click Next

↪ Switch to the tab Target Folders
↪ Click Add Target Folder…

↪ Add a target folder named src

↪ Click Finish

↪ Create a new Package in the resource folder asrc

↪ Name your package com.actifsource.simpleservice.generic as shown above
↪ Click Finish

↪ Change the style for Package Presentation as you like

↪ Start with a Class Diagram of your generic domain model
↪ Create a new Class Diagram in the Package generic

↪ Name your Diagram ServiceDesign
↪ Click Finish

↪ Insert the following Classes using the New Class Tool from the Palette: Service, Call, Parameter and Type

↪ Specify the Relations between your Classes using the Relation Tool from the Palette on the right
↪ First, link Service and Call by clicking on Service and then on Call in the diagram

↪ Select the Composition

↪ Insert another Composition between Call and Parameter

↪ Insert a Association between Parameter and Type

↪ Insert a Association between Call and Type

↪ Name the relation returnType
↪ Choose SubjectCardinality 1..1 since we always want a return type in this example
↪ Click Ok

↪ Adjust the subjectCardinality of the call Relation

↪ Change the subjectCardinality from Cardinality0_N to Cardinality1_N
↪ Use Content Assist (Ctrl+Space) and select the desired Cardinality

↪ Make sure to change all marked cardinalities as shown above
↪ Choose subjectCardinality Cardinality1_1 for the relations type and returnType

↪ Create a new Package specific in simpleservice

↪ Select the Package specific
↪ Use the New Resource Tool to create a Resource of type Service

↪ Name the Service Patient
↪ Click Finish

↪ Use the context menu on the Relation call to explore your options
↪ Press Enter to create a Resource of type Call for the Patient Service

↪ Enter the name Create by pressing enter on name or use the context menu
↪ Enter a new Parameter by pressing enter on parameter or use the context menu
↪ Enter the name LastName of the created Parameter

↪ Activate Content Assist (Ctrl+Space) to insert a Resource of type Type
↪ Create a new Type String using Content Assist (Ctrl+Space)

↪ Name the new Type String
↪ Switch back to the Service Patient by clicking the Patient Tab or by pressing Alt+Left to navigate to the last edit location

↪ Select parameter
↪ Insert a new Parameter using Insert After (Ctrl+Enter) or Insert Before (Alt+Shift+Enter)

↪ Name the Parameter FirstName
↪ Insert the already created Type String using Content Assist (Ctrl+Space)

↪ For returnType create a new Type int using Content Assist (Ctrl+Space)

↪ Select call
↪ Insert a new Call using Insert After (Ctrl+Enter) or Insert Before (Alt+Shift+Enter)

↪ Edit the Call Delete as shown above
↪ Insert Parameter Id of Type int
↪ Insert returnType boolean

↪ Create a new Package types in generic
↪ Move the Types boolean, int and String into the Package types using drag & drop

↪ Activate Link with Editor to link the Project Explorer with the editor

↪ Create a new Package template in simpleservice

↪ Select the Resource Service
↪ Choose New Template from the context menu

↪ Choose the Package template using Content Assist (Ctrl+Space)

↪ Name the template ServiceImpl
↪ Click Finish

↪ Place the cursor on the Filename Line
↪ Use Content Assist (Ctrl+Space) to insert a Variable
↪ Choose the Resource Service

↪ Press ‘. ’ (dot) after Service
↪ Content Assist opens automatically.
↪ Press Ctrl+Space to reopen Content Assist manually
↪ Select the Attribut name for Service

↪ Add the postfix Impl to the file name
↪ Add the language extension .java to the file name
↪ Save the file → a new file in your Target Folder src is created

↪ Write a Java Class as shown above. Make sure the class name contains the Variable Service.name
↪ Use Content Assist (Ctrl+Space) to insert the Variable
↪ Or use Copy/Paste (Ctrl+C/Ctrl+V) to copy the class name from file name
↪ Save the file (Ctrl+S) → Generated code can be found in the target folder src

↪ Place the cursor in the class body
↪ Use the tool Insert Line Context (Alt+Insert) from the tool bar

↪ Attach the Sub Context to the Parent Context using the Selector
↪ The given Selector must therefore navigate from Service to Call using Service.call
↪ Use Content Assist (Ctrl+Space) to specify the Selector
↪ Press Enter in the Selector to return to code

↪ Write a function in the Call Context as shown above

↪ Place cursor between the brackets
↪ Use the tool Insert Column Context (Alt+Shift+Insert) from the tool bar

↪ Write a parameter list in the Parameter Context as shown above
↪ Don’t forget the ‘, ’ (Comma) at the end
↪ Save the file (Ctrl+S). The generated file should contain a Java class , its methods and parameters

↪ Select both the comma and the following space
↪ Choose Not Last (Alt+3) from the tool bar
↪ Save the file (Ctrl+S). The generated file should contain a class , its methods and parameters

↪ Place cursor in the function body
↪ Insert a Protected Context in the function body with the tool shown above

↪ Write any text in the Protected Context, e.g. a TODO comment

• 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 the following package structure

Create a Generic Domain Model

• Create a Generic Domain Model in the DiagramEditor named ServiceDesign in the Package generic

• The Design shall contain the following Domain Classes

  • Service, Call, Parameter, Type

• Insert a Composition between

  • Service and Call

  • Call and Parameter

• Insert a Association between

  • Call and Type

  • Parameter and Type

• Adjust the Cardinalities as shown above

Warning: The layout for the relations transition and targetState might differ in your editor

Create a Specific Domain Model

• Create a Service named Patient in the Package specific

• Add the Calls Create and Delete

• Add the Parameter LastName, FirstName and Id as shown above

• Add the returnTypes as shown above

• Create a Code Template named ServiceImpl in the Package template

• Write code as shown above

• The function shall be placed in the Context Call Selector is Service.call

• The function parameters shall be placed in the Context Parameter; Selector is Call.parameter

• Save the Code Template

• You’ll find the generated code PatientImpl.java in the Target Folder src

• Use Java Functions to

  • extract recurring text fragments from your templates

  • capture complex expressions to keep your templates clean and easy to read

• Use Java Classes generated from your Generic Domain Model to write and maintain complex Java Functions

Extract Function

• We should extract identical terms to honor the DRY principle (Don’t Repeat Yourself)

• In your template select the text you want to extract into a function
• The light bulb at the left hand indicates Quick Assist is available

• Activate QuickAssist by clicking the light bulb or by pressing Ctrl+1
• Click Extract JavaFunction

• Name the function className
• Click Finish

Using Function

• The new function className returns the extracted fragment from your template
• The static function className is added to the static Java class ServiceImpl.ServiceFunctions in class ServiceImpl; this class is automatically generated by actifsource
• The term Service.name_Impl has been replaced by the function Service.className
• Java Functions are shown in italics in the actifsource Template Editor

• Let’s replace the second occurrence of the term Service.name_Impl
• Use Content Assist (Ctrl+Space) on Service to insert the function className for your class name

• Open the underlying Function Model (Ctrl+Alt+Left-Click)
• Alternatively, you can use the Tool Open Link in JavaEditor from the actifsource Template Editor toolbar

Editing Functions

• Change function declaration here if needed
• Please notice that the Function declaration was placed in the template

• Open the underlying Java Function (Ctrl+Left-Click)
• Alternatively, you can use the Tool Open Link in JavaEditor from the actifsource Template Editor toolbar

• The class ServiceImpl is opened in the Java Editor showing your function className

• Make sure to place additional imports within the corresponding Protected Regions
• Please note that all code outside Protected Regions will be overwritten if the respective source file is re-generated.

• Function Declarations are managed as actifsource Resources
• All Function Declarations are placed in Functions Spaces
• Templates are Functions Spaces by default
• Functions Spaces can exist without Templates
• Function Spaces are Resources and can therefore be placed in Packages

Advanced Context Operations

• Let’s add a new line after the Call Context in the Service Context
• Place cursor on the last position of the Call Context

• Press Cursor-Right
• While the cursor stays at its position, the Service Context is now highlighted
• Alternatively, you can use the context navigation from the actifsource Template Editor toolbar

• Press Enter
• A new line has been added in the Parent Context

Add Context via Quick Assist

• Let’s look at a quick and easy way to insert a new Context
• Insert the Variable Service.call using Content Assist (Ctrl+Space)

• The light bulb at the left hand indicates Quick Assist is available
• Activate QuickAssist by clicking the light bulb or pressing Ctrl+1

• Click on Create Line Context

• The Variable Service.call has been replaced by Call

Built-In Functions

• Let’s use Built-In Functions on Attributes
• Press '.' (dot) and Content Assist (Ctrl+Space) after name to see all available Built-In Functions

• Complete the member variable declaration as shown above

Extract Function in Function Space

• Call.name_Impl shall be the name of a new Template
• Select the term Call.name_Impl
• Activate QuickAssist by clicking on the light bulb or pressing Ctrl+1
• Click Extract TemplateFunction
• Template Functions behave like templates and are easier to handle than Java functions

• Name the function className
• Click New Template to create a new template which acts as Function Space for the new function className

• Check the Package
• Name the Template CallImpl
• Press Finish

• Press Finish

• The Term Call.name_Impl has been replaced by Call.className@CallImpl
• className@CallImpl indicates that the Function className belongs to the Function Space CallImpl

• A new Template named CallImpl has been created in the Package template
• Use the Function className in the file line of your template

• Write a simple class as shown above
• Write a method execute with returnType and Parameter
• Please notice that you might copy the whole parameter expression from the ServiceImpl Template
• Place a Protected Context in the function body

Templates and Folders

• Open the underlying Template Function for className (Ctrl+Left-Click)
• Alternatively, you can use the Tool Open Link in JavaEditor from the actifsource Template Editor toolbar

• The function className is handled as a Template Function (partial template)
• Template Functions are easy to handle
• A TemplateFunction may call itself to follow recursive meta model designs (Composite Pattern)

• Generated artifacts are placed in the Target Folder of your project

• You may want to place generated artifacts in specific sub folders

• Add Service.name/ as folder information in the file line of the Template ServiceImpl as shown above

• We want all Call implementations to be generated in the same folder as their corresponding Service
• Add Service.name as the folder name in the file line of the Template CallImpl as shown above
• Save the Templates CallImpl and ServiceImpl
• Protected Regions of the generated files are preserved

Copy with Context

• Extract a TemplateLineFunction memberName for the member variable name

• Also use the function memberName in the function body as shown above

• Open the underlying TemplateLineFunction for memberName (Ctrl+Left-Click)
• Alternatively, you can use the Tool Open Link in JavaEditor from the actifsource Template Editor toolbar

• The function className is handled as a TemplateLineFunction
• Template Line Functions are the easiest way to reuse information
• Template Line Functions do not allow context

• We want to copy Parameter.name including the Parameter Context and the separating comma from the functions parameter list
• Select the Term Parameter.name
• From the Context Menu, select Copy with Context
• From the Subcontext Menu, select Parameter

• Place your cursor between the brackets
• Select Paste from the Context Menu (Ctrl+V)

• The text and its corresponding context are inserted

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

• Create a simple state machine
• Instantiate the state machine and see its deficits

Create a Generic State Machine Model

• Create a Generic Domain Model named Design in the Package generic using the DiagramEditor
• The Design shall contain the following Domain Classes
  • Statemachine Event State Transition

• Insert a Composition between

  • Statemachine and Event
  • Statemachine and State
  • State and Transition

• Insert a Association between

  • Transition and State

• Adjust the Cardinalities as shown above

• Warning: The layout for the relations transition and targetState might differ in your editor

Create a Specific State Machine

• Create a Statemachine named Statemachine1 in the Package specific

• Add the Events start and stop
• Add the States Initialized Started and Stopped as shown above

Part III Decorating Relation Aspect

• Learn how to decorate a relation with a list of resources in order to prevent the mixing of instances from different Statemachines

Add a Decorating Relation Aspect

• In State open the Composition transition
• Press Enter on aspect[DecoratingRelationAspect]

• Select ResourceSelectorAspectImplementation
• Click OK

• Let's look at a possible Transition for every Event
• The Composition transition is found in State
• We have to navigate from State to Event
  • Navigate backwards from State via state to Statemachine
  • Navigate forward from Statemachine via event to Event

• Enter the Selector State.-state.event using Content Assist (Ctrl+Space)

• Implementing a DecoratingRelationAspect asks for a subclass of Decorator

• Decorator has a useRelation target which is used to store the specific decorating Resource

  • Shown as: decoratingRelation[target]

• Open Quick Assist by clicking the light bulb or press Ctrl+1

• Use Quick Assist to let Transition extend Decorator

• Open Transition
• By default a Class extends NamedResource
• The Quick Assist Action changed the extends statement from NamedResource to Decorator

• Quick Assist has done the following
  • Added extend Decorator
  • Added Association event

• The range of Decorator.target is Resource and therefore untyped in the context of your domain
• The new Association target extends Decorator.target but with Event as its range
• When writing template code, you are able to access Transition.event typed as Event

Use the Decorating Relation Aspect

• Open the specific Statemachine Statemachine1
• Add new Events and observe the decoratingRelation transition

• In the State Initialized create a new Transition for transition[start]
• Select Started as targetState

• Configure the State instances Started and Stopped as shown above

• Content Assist (Ctrl+Sapce) in actifsource shows all instances of a desired type; It is often useful to restrict this selection
• Learn how to apply range restrictions to filter instances for a given type

Without Range Restriction

• Let's discover the needs for a range restriction aspect
• Create a Statemachine named Statemachine2 in the Package specific
• Add the Event instances open and close
• Add the States instances Initialize Opened and Closed

• Create any new Transition
• Use Content Assist (Ctrl+Space) to add a targetState of type State

Add a Range Restriction Aspect

• In Transition open the useRelation targetState

• Press Enter on aspect[RangeRestrictionAspect]

• Select ResourceSelectorAspectImplementation
• Click OK

• Let's restrict the range of targetState to instances of States owned by the own Statemachine

• The useRelation targetState is found in Transition

• We have to navigate from Transition to all States of the Statemachine

  • Navigate backwards from Transition via transition to State
  • Navigate backwards from State via state to Statemachine
  • Navigate forward from Statemachine via state to State

• Enter the Selector Transition.-transition.-state.state using Content Assist (Ctrl+Space)

Use the Range Restriction Aspect

• Use Content Assist (Ctrl+Space) again to add the targetState Opened of type State

• Get familiar with Decorating Relations and Range Restrictions
• Write an actifsource Code Template to generate a state machine

• Write a code template for instances of Statemachine

Write a code template for Statemachines

• Create a package ch.actifsource.tutorial.statemachine.template
• Select the new package and choose New->Template from the context menu.

• Insert StatemachineImpl as Template Name
• Choose the Base Type ch.actifsource.tutorial.statemachine.generic.Statemachine
• Click Finish

• Insert Statemachine.name on the Filename Line and make sure that the language (C++) is automatically detected.
• Write the skeleton for a class Statemachine.name

Next, we define an enumeration variable with the all the States of a Statemachine as enumerators. This variable stores the current state of a Statemachine

• Write the declaration of enumeration variable m_aState
• Insert a LineContext in the enumeration list and choose the Selector Statemachine.state with the support of the Content Assist
• Insert State.name in the newly created LineContext. Append a ','. Then mark the ',' and select NotLast to make sure that there is no comma after the last entry in the enumeration list.

We define a member function for each event of our Statemachine which will later handle all the possible transitions triggered by the event:

• Create a new LineContext and choose Statemachine.event as the selector of the line context
• Write the skeleton of a function returning void named Event.name

We write a switch-statement with the current state m_aState as control variable and define a LineContext that iterates over all Transitions referring to an Event through the relation Transition.event

• Create a switch-statement with the m_aState as control variable
• Create a LineContext inside the switch-statement
• Choose Event.-event as the Selector of the new LineContext

We create a LineContext that iterates over all States that refer to a Transition through the relation State.transition

• Create a LineContext on the same line as LineContext that we have crated before
• Choose Transition.-transition as the Selector of the new LineContext

We write a case-statement for each State that is (indirectly) referring to an Event through State.transition.event

• Insert a case State.name and add a break at the end of the case-statement

We update the current state as follows: We first select for an Event the Transitions that refer to the Event trough Transition.event For each Transition we select the States that are connected to Transition by State.transition For each State it holds that if the current state m_aState is equal to State then the new State of the Statemachine is Transition.targetState

• Write code to assign Transition.targetState.name to the variable m_aState

In order to generate code from the template we have implemented before, we setup the project properties for Actifsource:

• Select the project ch.actifsource.tutorial.statemachine and choose Project->Properties from the main menu

• In the Properties dialog choose Actifsource and select the tab Target Folders

• In the dialog Select Target Folder, click on the button Create folder

• Enter src as Folder Name in the New Folder dialog

• Click on OK in the New Folder dialog and then in the Select Target Folder dialog

• Check the settings on the Target Folders tab and close the dialog by clicking on OK

The code generator now applies the template StatemachineImpl to the two Statemachine instances and stores the resulting files to the src folder:

• Open the src folder and check that the two files Statemachine1Impl.hpp and Statemachine2Impl.hpp have been generated
• If the files have not been generated, make sure that Generate Automatically is active under Project in the main menu

• Open the newly generated files and inspect and compare the code for the two Statemachines
• Learn how to extend the Statemachine by conditional transitions and actions executed together with a transition by working through the Actifsource Tutorial Code Snippet
• Complete the generated classes by adding a member function initialize()

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

• Instances of Language describe the following language elements

  • Keywords
  • Single Line Comments
  • Multi Line Comment
  • Color and font type

• Let’s create an new Language instance for a fictitious math language

• Select the package language
• Use the New Resource Tool to create a Resource of type Language

• Name the Language Math

• Click Finish

• Define the file name extension for the new language
• Define your keyword style: color DarkRed, fontModifier Bold
• Define your keywords: var, add, sub, mul, div
• Define your single line comment style: color DarkGreen, fontModifier Italic
• Define your single line comment tag: #
• Use a StringStyle to define string coloring

• The actifsource template editor is now supporting the new Languagefor the specific file extensions
• Let's test the new syntax highlighting

• Create a new Template in the Package language

• Name the Template Test
• Click Finish
• Ignore the warning “No build config selected.”

• In the file line, choose the file extension .math
• The Language is Math selected automatically
• Use Content Assist (Ctrl+Space) to select the language manually (i.e. if there is no file extension)
• Use Ctrl+Click on the Language to open the Language Resource

• Add some Code using the new keywords
• Try to write some comments

• Prepare a new actifsource Project as seen in the Actifsource Tutorial Simple Service with name and namespace ch.actifsource.tutorial.literal.aspect as shown in this tutorial

• Create a new class as shown in the picture with name Component and one attribute
• As you can see in the content assist, there is no Literal for representing a date.
• Create a new Literal using the content assist

• Set the name to DateLiteral
• For the moment there is not much more we can do, since we first need to setup the project.

• First we need to to convert this project to a Eclipse Plugin Project
• Right click on the project ch.actifsource.tutorial.literal.aspect in the navigator to open the context menu.
• Go into the submenu Configure and click on Convert to Plug-in Projects…

• Check the checkbox in front of ch.actifsource.tutorial.literal.aspect
• Click Finish

• This will convert the project however there will be some error and warning needed to be fixed.

• Right click on the Actifsource classpath container
• Go into the submenu Build Path and select Remove from Build Path

• Open the MANIFEST.MF

• Now you have a Plug-In project and need to set the dependencies to actifsource plugin defining the Literal Aspect. In this case it is the ch.actifsource.core"-Plug-In.
• Add a dependency to the ch.actifsource.core" and the ch.actifsource.ui.refactoring-Plugin

• Create a new java source folder for the aspect implementation.
• We recommend naming the new source folder src
• Click Finish

• After the project setup, we are ready to create a java class using an actifsource core interface
• Java Class implementing the ch.actifsource.tutorial.literal.aspect.ILiteralAspect.

• There are four methods to implement
• getValueType The java type representing the literal value. In our case the java “Date” class.
• getValue A conversion method to convert the literal value to an instance of the value type, which may return “null”, if the value is invalid
• allowMultiLine True, to allow the use to type in multiple lines using line breaks
• isValid Returning an error string if the value is invalid or “null” if valid
• Implement the LiteralAspect as following

package ch.actifsource.tutorial.literal.aspect;

import java.text.DateFormat;
import java.text.ParseException;
import java.util.Date;
import java.util.Locale;

import javax.annotation.CheckForNull;


import ch.actifsource.core.INode;
import ch.actifsource.core.job.IReadJobExecutor;
import ch.actifsource.core.model.aspects.ILiteralAspect;
import ch.actifsource.core.scope.IResourceScope;

public class DateLiteral implements ILiteralAspect {

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

  @Override
  public @CheckForNull Object getValue(IReadJobExecutor executor, IResourceScope arg1, INode value) {
    DateFormat dateInstance = DateFormat.getDateInstance(DateFormat.LONG, Locale.ENGLISH);
    try {
      return dateInstance.parse(value.toString());
    } catch (ParseException e) {
      return null;
    }
  }

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

  @Override
  public @CheckForNull String isValid(IReadJobExecutor executor, IResourceScope scope, String value) {
    DateFormat dateInstance = DateFormat.getDateInstance(DateFormat.LONG, Locale.ENGLISH);
    try {
      dateInstance.parse(value.toString());
      return null;
    } catch (ParseException e) {
      return e.getMessage();
    }
  }

}

• Go back to the “DateLiteral” and add new value for the aspect [LiteralAspect] relation.

• Type “Date” and use the content assist to select the class.

• The Literal is now ready to use, since we created the Literal early with the content assist, the attribute in the “Component” is already using it

• To test the literal, just create a new instance of the “Component” and define a “releaseDate”.

Setup a project

• Open the project created during the Actifsource Tutorial Simple Service or make an new one with the new project with name and namespace ch.actifsource.tutorial.refactoring as shown in this tutorial
• Create a new Package with name refactoring
• Create a Refactoring resource of type ch.actifsource.ui.refactoring.Refactoring with name Refactoring

• You need to convert this project to a Eclipse Plugin Project
• Right click on the project ch.actifsource.tutorial.builtin in the navigator to open the context menu.
• Go into the submenu Configure and click on Convert to Plug-in Projects…

• Check the checkbox in front of ch.actifsource.tutorial.refactoring
• Click Finish

• This will convert the project however there will be some error and warning needed to be fixed.

• Right click on the Actifsource classpath container
• Go into the submenu Build Path and select Remove from Build Path

Create and register a refactoring aspect

• Open the MANIFEST.MF

• Add a dependency to the ch.actifsource.core" and the ch.actifsource.ui.refactoring-Plugin

• Create a new java source folder for the aspect implementation.

• We recommend naming the new source folder src-aspect
• Click Finish

• Create a new java class extending the ch.actifsource.core.model.aspects.impl.AbstractRefactorerAspect class

• Add the following constructor function to the class

public CallGroupRefactoringAspect() {
  super("1.0.0",
        Date.from(LocalDate.of(2024, 1, 6).atStartOfDay(ZoneId.systemDefault()).toInstant()),
        "Call to Callgroup");
}

• The first parameter defines a version string for the aspect. The following three parameters are used to specify the date when the refactoring was written.The last parameter is the name. The arguments are shown in the dialog and used to sort the refactoring aspects.

• Register the java class in the Refactoring instance

• The result should look like above. There must be no more model inconsistencies be present.

• Open the Service class
• Select the call relation and cut the resource by using the clipboard (Ctrl+X)

• Create a new Relation named group with a new Class named “CallGroup” used as the range

• Paste the call relation from the clipboard into the new Callgroup

• Add an additional Attribute named async of type boolean with default value false
• We only use an attribute to keep the tutorial simple. An alternative would be to create a subclass of CallGroup instead.

• First we want to have more convenient access to the resource guids.
• To accomplish this, we need to check a setting in the project settings of ch.actifsource.tutorial.refactoring
• Right-click on the project and select Properties

• Check in the actifsource settings whether the option “generate javamodel” is set

• If the “generate javamodel” option is not set, this can be set or add a the ExportWithoutStatements buildconfig to the src-gen target folder for exporting java classes for the SimpleService packages
• This will generate a class for each package containing a constant for each resource.

-If you cannot use the buildconfig ExportWithoutStatements, check in the Built-in Dependencies tab whether the JAVAMODEL is available. If not, add it via the Add Builtin button.

• Implement the refactor method

• The refactor method has only two parameters an IModifiable and a list of packages. The modifiable provides the context to access the actifsource resources. The package list contains the actifsource packages selected by the user when starting the refactoring. How the packages selection is interpreted is up to the implementer.

• In general you need to use the two classes Select and Update. These are facades providing a convenient way to select and update resource information in a context. To get information about the available methods, open the class and a have a look at the javadoc comments on how to use them.

• The actifsource API works with statements and resources. A Statement is a triple connecting two resources (subject, object) through a property (predicate). The subject is the resource whose type (class) defines the predicate (property). The object is an instance of properties range. This is almost the same you see in the resource editor. In our example Patient is an instance of Service Person refers the Call throw the call defined in the Service class. For example you will get a statement Person (subject), call (predicate), Create (object) because Person refers to Create through the call relation. This is different from the diagram editor where subject and object are represented by their type.

• The old model looked like this

  

  and the new model looks like this now

  

The only thing the refactoring has to do is adding a CallGroup into each Service and move the Call into the group.

• Select all Service instances in packages posted to the refactorer
• The instanceWithPackage method takes an ISelectable and the GUID of a class. The result is an Iterable providing all instances reachable through the selectable. Since each IModifiable is also an ISelectable, you can use the IModifiable passed to the refactorer.

• Create a new CallGroup using the Update-Facade and add it to the Service-Instance
• The Update-Facade always requires an IModifiable to work with. Using the createAndInitializeResource method you can create a new instance of a type in the specific package. If you have a named resource, it is recommended to use the overload taking a name, in this case group. The last parameter defines the default values for the attributes and relations when creating the resource and can be left out. For each property not found in the defaultValue map the default defined in the model will be used.

• Move the Call to the group
• This time the method is located on the RefactorUtil. The reason for this is that the Update-Facade only provides simple modification methods and no selects. The moveStatements method uses methods from both the Select and Update method and is more complex. The moveStatements method take the IModifiable, a Property, the source and the target. It is simply often used when moving a Property from one class to another.
• By using the cut and paste in ResourceEditor, actifsource automatically detected that you have moved the Property call

• Open the Patient to see that it is actually invalid.
• As you can see the group relation that is already there and it would be possible to do change the model by hand.

• Open the context menu on the project or the package containing the Patient service

• Select the Call to Callgroup.
• Press Finish.

• The Patient service is now refactored
• As you can see, the values passed to the constructor are shown in the refactoring dialog. In actifsource we use the aspects to provide refactorings whenever we change the metamodel.

Part IV Update the templates

• The refactoring you have written only updates the instances. This is common practice, writing a refactoring for the service model and the templates makes no sense, since updating the classes is different for each step. The same applies for the templates.
• Open the ServiceImpl template
• Go to the Service.call selector by clicking on the first errormarker
• Change it to Service.group.call

• Add a new line using the async attribute

• Open the generate PatientImpl.java and update the protected regions.

• Since creating a builtin doesn’t make sense without having a model, just create an actifsource project name ch.actifsource.tutorial.builtin with some resources.

• YourClass is a NamedResource

• Right click on the project ch.actifsource.tutorial.builtin in the navigator to open the context menu.
• Go into the submenu Configure and click on Convert to Plug-in Projects…

• Check the checkbox in front of ch.actifsource.tutorial.builtin
• Click Finish
• This will convert the project however there will be some error and warning needed to be fixed.

• Right click on the Actifsource classpath container
• Go into the submenu Build Path and select Remove from Build Path

• Double click on the MANIFEST.MF to open the manifest editor

• Go to the build.properties tab
• Click on the yellow warning sign left to the source.. line
• Select Add src-gen/ to the source.. build entry, if it is not already there.
• This will add the src-gen folder to the source build when exporting a plugin including source code. This is not a requirement to export the actifsource model as builtin however we want to get rid of this warning
• There may be more warning depending on your eclipse configuration, you may fix them the same way if you like.

• Activate the Dependencies tab
• Click on Add...
• Enter ch.actifsource.core in the textbox to start filtering
• Select ch.actifsource.core
• Click on Add

• If you do the conversion on an existing project, you may need to add additional dependencies. You might see this by looking into the generated files, the actifsource project dependencies and the java build path.

• When exporting a model as plugin, you have to make sure that you have a plugin dependency to all required projects. This means all required projects need to be converted into plugins.

• Before defining exports you need to have access to the required extension point declarations. This is done by adding a dependency to ch.actifsource.environment.

• Go back to the Dependencies tab in the manifest editor
• Click on Add…
• Enter ch.actifsource.en to start filtering
• Select ch.actifsource.environment
• Click on Add

• Activate the Extension tab
• Click on Add…
• Select ch.actifsource.core.RegisterModel
• Click on Finish

• You don’t need to specify an ID and Name for the extension, we leave it empty.
• Open the context menu by right click on the extension
• Go into the Submenu New and select ResourceFolder

• Select the empty (ResourceFolder) entry

• Enter the project relative path asrc to the resource folder

• You may define different resource folders as defined in your actifsource project configuration. This is useful if you want to write templates inside your plugin to generated code and don’t want to deliver the template and related resources. Just put the templates in a separate resourcefolder which is not registered in the extension.

• Switch to Build tab
• Check the asrc Folder in the binary build
• This is needed to include the asrc in the binary release, if you fail to do so the plugin won’t contain any resources.

• A builtin provides a way to define dependencies to actifsource model defined in a plugin inside a non-plugin projects. This step is not required if you want to use your model only in plugin projects.

• Go to the Overview tab
• Make sure you, that the plugin ID is ch.actifsource.tutorial.builtin

• Switch back to Extension tab
• Click on Add…
• Select ch.actifsourc.environment.RegisterBuiltin
• Click on Finish

• Select the predefined (Builtin) entry
• Define a name EXAMPLE_BUILTIN
• The other options are not used in this example:
  • defaultBuiltin If true, the builtin will be added by default whenever a new actifsource project is created and must be explicitly removed.
  • isExtendable If true, other plugins are allowed to define a builtin with the same name. This will result in merging the dependencies together. You may find this useful, if you provide extensions to your builtin, which you want to have automatically applied as soon as a plugin is installed.

• Select the predefined (Plugin) entry
• Enter the pluginId of your plugin ch.actifsource.tutorial.builtin
• This is not required to be the plugin defining extension point, this might be useful if you don’t want to have a plugin dependency to ch.actifsource.environment in the plugin providing the resourcefolder.

• In order to deliver a plugin you need to create an eclipse feature containing the plugin and a updatesite where the feature is published

• Open the menu File
• Go into the submenu New
• Select Project…

• Select Feature Project
• Go to the next page.

• Enter the project name ch.actifsource.builtin.feature for the feature
• As you can see, the default feature ID is set to the project name.
• Press next to step further

• Select the plugin ch.actifsource.tutorial.builtin
• Exit the wizard using Finish

• Eclipse will ask you if it should open the associated Plug-in Development perspective
• Answer this question by click on No

• After finishing the wizard of feature editor will open automatically.
• Switch to the Dependencies tab
• Press Add Feature…
• Select ch.actifsource
• Hit OK
• This will add actifsource enterprise as dependency, disallowing to installing the feature without having actifsource installed. As a result eclipse will automatically select actifsource enterprise for installation if the location of actifsource is known and contacting other updatesites is enabled (see later)
• In order to make the feature visible on the updatesite, you need to create a category otherwise eclipse will hide the feature in the categorized view of the installation wizard.

• Open the File menu
• Select New
• Click on Other…

• Select Category Definition
• Press the Next button

• Select your feature ch.actifsource.tutorial.builtin.feature
• This is only the location of the file, this doesn’t associate the feature with the category.
• Leave the filename unchanged and press Finish

• Press New Category
• Enter the id actifsource.tutorial.category
• Enter the name Tutorial Category

• Select the category
• Press Add Feature…
• Select the your feature ch.actifsource.tutorial.builtin.feature
• Press the Add button
• At this point we are ready to export the feature to an updatesite

• Right click on the feature.xml
• Select Export…

• Select Deployable features
• Click on Next

• Select Options
• Click on Browse…

• Select category.xml
• Close with OK

• If you don’t want to increase the micro version each time you export, it is recommended to set a qualifier. Failing to change the version or qualifier will cause eclipse to not overwrite an existing on the update site.
• Check the Qualifier replacement checkbox
• Enter the current date and time in reverse order
• Be careful if the major, minor and micro version of two versions are the same, a text comparison between the qualifiers is done. This means write the date the other way around will cause eclipse to select the wrong latest version.

• Go back to the Destination tab
• Enter the location of the updatesite, we use $HOME\updateSite
• Depending on your installation you may have to choose a different directory, where you have write access.
• Press Finish

• For this step you need to have installation rights on the running eclipse. To get around this, you may download a new eclipse from www.eclipse.org and test it on a writable location.

• Go Help
• Select Install New Software….

Install the example feature

• Enter the location of the updatesite, we used file:/c:/tmp/updateSite
• Eclipse requires the use of the file-URL. In order to distribute the updateSite on the web, just upload the content of the directory to your webserver.
• Check Contect all update sites during install to find required software
• This option uses the required feature defined in the feature where we added the ch.actifsource.
• Press Next

• This dialog will show addition features if eclipse found missing feature required for installation. However you will see an error message if any feature is missing that wasn’t found. This happens when eclipse doesn’t know an updatesite containing the feature. Another reason for installation failures are conflicts between installed versions, you may need to uninstall conflicting plugins first or try to update all at once using the Check For Update dialog
• Press Next

• Read the license(s)
• Accept the license
• Press Finish
• Eclipse will start downloading the required features and plugins from the updatesites

• Before starting the installation of a feature, eclipse will check if the feature and the plugins are signed. This option can be activate in the export wizard, however this goes beyond this tutorial. Simply accept all certificates by clicking on the Trust Selected button
• Since we know from the verification dialog, that only our feature is going to be installed, safely click OK

• Press Yes to restart

• Now we can use the builtin. You have two options, creating a plugin dependency or adding the builtin in the actifsource preferences

• Select File
• Go to New
• Click on Project…

• Enter a project name for the usage, we use ch.actifsource.tutorial.builtin.usage
• Switch to the Next page

• Activate the Built-in Dependencies tab
• Click on Add Builtin…
• Select EXAMPLE_BUILTIN
• Hit OK
• Finish the wizard and you are ready to go
• As mentioned when defining the builtin this step can be omitted if you have defined builtin with the defaultBuiltin-attribute set to true.

• Create a simple design consist of a club, containing members having a date of birth

• Club is a NamedResource

• Club owns 1..N Member

• Member is a Resource

• Member contains the following Attributes of type StringLiteral:

  • firstName
  • lastName

• Member owns 1*1 DateOfBirth

• DateOfBirth is a Resource

• DateOfBirth contains the following Attributes of type IntegerLiteral:

  • Year
  • Month
  • Day

• Create your own name aspect for Member

• Create your own name aspect for DateOfBirth

• Create a simple html template to display all club members and their birthdays

• The generated result should look like shown above

• Create a new FunctionSpace called MyFunctions
• Create a new FunctionContext for the typeRef Member

• Create a new JavaListFunction called sortByDateOfBirth
• Select GenericContextListType as returnType
• Please note that the GenericContextListType automatically converts to the same type as used as the function target in the selector
• You will love this feature if your type (typeRef) has sub classes
• Imagine to create a sortByName function for NamedResource
• Calling A.sortByName for A as a sub class of NamedResource will return A as the type of result and not NamedResource even sortByName has been defined for NamedResource

• After saving the FunctionSpace MyFunctions the folder src-gen will contain a Java file named the same as your FunctionSpace
• Find the generated function body for the JavaListFunction sortByDateOfBirth
• Let’s write some Java code to sort our club members by their date of birth

• Since the memberList passed by Actifsource is marked final we have to copy the list in order to modify\

  ArrayList<T> memberListSorted = new ArrayList<>(memberList);

• Return the copied list to get rid of compile errors\

  return memberListSorted;

• Please make sure to place the import statement for ArrayList in the ProtectedRegion
• Otherwise the your import will be overwritten from the generator

• Using the static function Collections.sort() from the Java collection framework allows us to pass a so called Comparator
• Let’s implement the anonymous class of type Comparator<T> as shown above
• Comparator.compare shall return 0 if objects are equal, -1 if o1 is a predecessor of o2, or +1 if o1 is a successor of o2
• Since the variables o1 and o2 are fully typed we can directly access the properties of Member using the selectXYZ() functions
• The code shown above is sorting dates regarding month and day only
• Try to implement a sort function which shows the oldest member first

• Use the sortByDateOfBirth function to sort any selected list of members by their date of birth

• As a result your members are sorted by month and day

• 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