• 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