yakindu/plugins/org.yakindu.sct.doc.user/help/user/04_Tasks/tasks.textile

h1. Tasks

h2. Modeling a statemachine

# Make sure the YAKINDU Modeling perspective is active.
# Create a new project.
# Click *File* > *New* > *Other...* > *YAKINDU* > *YAKINDU Statechart Model*. 
# Click *Next* name the sct file and click *Finish*
# The YAKINDU statechart editor opens on the statechart model. It already has an initial state and an unnamed simple state connected by a transition.
# Now you can add states and transitions from the palette.

To edit the states and transitions you can use the properties view. It has an integrated Xtext support. This makes correct editing easier. You can also change the appearance of the model elements. 

On the palette you will also find a composite submachine state. This is a state that contains a complete statemachine. You can choose an existing statemachine or create a new one.

h3. Related topics

"Statemachine Elements reference":../05_Reference/reference.html#Statechartelements
"Textual modeling lanuage  Reference":../05_Reference/reference.html#Statechartdescriptionlanguage


h2. Validating a statemachine

The statemachine is validated automatically during build. The elements that cause problems get error markers. You can find the details about the problems on the problems view.

h2. Simulating a statemachine

The YAKINDU simulation engine supports simulation modes:

* event driven
* cycle based

The default setting is _cycle based_ with a cycle period of 200 ms. In this mode the simulation engine processes the state machine transitions in steps of the given cycle duration. The following statechart illustrates this. It is simulated cycle based with a cycle period of 3 seconds.

!images/cycleBasedVsEventDriven.png!

What happend during simulation is the following:

# After 3s *init* switches to *pre1*
# After 3 further seconds recursive transition to *pre1* is processed (not after 2s the transition says)
# After 3 further seconds recursive transition to *pre1* is processed again and the condition becomes *true* so *result* gets activated

In contrast to cycle based the event driven simulation mode concentrates on the events of a state machine. The same state machine above could be simulated as follows:

# Immediately *init* switches to *pre1*
# Immediately the event *touch* is raised twice
# The condition becomes true so that the *result* state is reached after 2 or 3 seconds instead of 9 

Start a simulation with the different modes as follows

# Make sure the YAKINDU Simulation Perspectiv is opened.
# Start the simulation by clicking *Run* > *Run Configurations...*.
# Select the statechart you want to simulate and the simulation mode.
# *Apply* the setting and *Run* the simulation.

!images/simulationRunConfiguration.png!

"Simulation Concept":../03_Concepts/concepts.html#Simulation
"Simulation perspective":../03_Concepts/concepts.html#YakinduSCSimulationperspective
"Simulation View":../03_Concepts/concepts.html#SimulationView

h2. Generating Code

For configuring the code generation process, YAKINDU Statechart Tools uses a textual generator model called *SGen*. It can be created either by using the provided wizard *Yakindu Statechart Generator Model* or by creating a new text file with the file extension '.sgen'.
To create a generator model with the wizard,

# Click *File* > *New* > *Other...* > *Yakindu Statechart Generator Model*
# Type a name and click *Next*
# Choose the desired generator, i.e. *YAKINDU Java Code Generator*
# Check the model(s) to generate code from and click *Finish*

!images/genmodelwizardchooselanguage.jpg!

The result is an .sgen file of the following format: 

bc.. 
GeneratorModel for [GeneratorId] {
	statechart [StatechartReference] {
		feature [Feature] {
			[ParameterName] = [ParameterValue]
		}
	}
}
p. The [GeneratorId] is the unique id of the Generator. Currently, the following Generators are supported out of the box:

# yakindu::java - Generator ID for the Java Code Generator 
# yakindu::c - Generator ID for the C Code Generator
# yakindu::cpp - Generator ID for the C++ Code Generator
# yakindu::xpand - Generator ID for custom Xpand based Code Generators
# yakindu::generic - Generator ID for custom Java based Code Generators  

One GeneratorModel can contain several [StatechartReference]s. These are cross references to statechart models for which the code should be generated. For each reference, the generator process can be configured with [Feature]s. Each Feature consists of several parameters. These parameters can be configured with [ParameterName] = [ParameterValue].
 
The Generator Model is executed by a builder. Thus, the artifacts are generated automatically if *Project* > *Build Automatically* is checked. If you want to execute your Generator Model by hand, select *Generate Statechart Artifacts* from the *Package Explorer's* context menu.

h2. Core Features

The following section describes the *Core Features* which are available for all code generators:

==<!-- Start sgen_feature_outlet -->==

h4. Outlet

The *Outlet* feature specifies the target project and folder for the generated artifacts. It is a *required* feature and consists of the following parameters:
# __targetProject__  (String, required): The project to store the generated artifacts  
# __targetFolder__  (String, required): The folder to store the generated artifacts

Example configuration:

bc.. 
feature Outlet {
	targetProject = "ExampleProject"
	targetFolder = "src-gen"
}
p. ==<!-- End sgen_feature_outlet -->==
==<!-- Start sgen_feature_licenseheader -->==

h4. LicenseHeader

The *LicenseHeader* feature specifies the license text that should be added as a header to the generated artifacts. It is an *optional* feature and consists of the following parameters:

# __licenseText__  (String, required): The license text to add as a header  

Example configuration:

bc.. 
feature LicenseHeader {
	licenseText = "Copyright (c) 2012 committers of YAKINDU and others."
}
p. ==<!-- End sgen_feature_licenseheader -->==
==<!-- Start sgen_feature_functioninlining -->==

h4. FunctionInlining

The *FunctionInlining* feature allows the inlining of expressions instead of generating separate functions or methods. This might reduce the readability of the generated code, but increases performance because less operation calls are necessary. 
It is an *optinal* feature and consists of the following parameters:

# __inlineReactions__  (Boolean, optional): Inlines the expression for reactions
# __inlineEntryActions__  (Boolean, optional): Inlines the expression for entry actions
# __inlineExitActions__  (Boolean, optional): Inlines the expression for exit actions
# __inlineEnterSequences__  (Boolean, optional): Inlines the expression for enter sequences
# __inlineExitSequences__  (Boolean, optional): Inlines the expression for exit sequences
# __inlineChoices__  (Boolean, optional): Inlines the expression for choices
# __inlineEnterRegion__  (Boolean, optional): Inlines the expression for enter regions
# __inlineExitRegion__  (Boolean, optional): Inlines the expression for exit regions
# __inlineEntries__  (Boolean, optional): Inlines the expression for entries 

Example configuration:

bc.. 
feature FunctionInlining {
	inlineChoices = false
	inlineEnterRegion = true
	inlineEntries = true
}
p. ==<!-- End sgen_feature_functioninlining -->==
==<!-- Start sgen_feature_debug -->==

h4. Debug

The *Debug* feature dumps the Execution Model to the target folder as xmi model. It is an *optional* feature and consists of the following parameters:

# __dumpSexec__  (Boolean, required): The license text to add as a header  

Example configuration:

bc.. 
feature Debug {
	dumpSexec = true
}

p. ==<!-- End sgen_feature_debug -->==

h2. Java Generator Features

==<!-- Start sgen_feature_naming -->==

h4. Naming

The *Naming* feature allows the configuration of package names as well as class name prefix / suffix.
It is an *optional* feature and consists of the following parameters:

# __basePackage__  (Boolean, required): The package to create for the generated java classes
# __implementationSuffix__  (Boolean, optional): The suffix for the implementing classes

Example configuration:

bc.. 
feature Naming {
	basePackage = "org.yakindu.sct"
	implementationSuffix = "Impl"
}
p. ==<!-- End sgen_feature_naming -->==	
==<!-- Start sgen_feature_generalfeatures -->==	

h4. GeneralFeatures

The *GeneralFeatures* feature allows to configure additional services to generate with the statemachine. Per default, all parameters are configured to __false__ It is an *optional* feature and consists of the following parameters:

# __EventBasedStatemachine__ (Boolean, optional): Enables/disables the generation of a cycle based statemachine implementation
# __InterfaceObserverSupport__ (Boolean, optional): Enables/disables the generation of listener interfaces for the statemachine
# __RuntimeService__ (Boolean, optional): Enables/disables the generation of a runtime service that triggers the runcycle of a cycle based statemachine
# __TimerService__ (Boolean, optional): Enables/disables the generation of a timer service implementation using __java.util.Timer__
# __GenericInterfaceSupport__ (Boolean, optional): Enables/disables the generation of generic interfaces
# __StatemachineFactorySupport__ (Boolean, optional): Enables/disables  the generation of a factory class

Example configuration:

bc.. 
feature GeneralFeatures {
	EventBasedStatemachine = true
	InterfaceObserverSupport = true
	RuntimeService = true
	TimerService = true
	GenericInterfaceSupport = true
	StatemachineFactorySupport = true
}

p. ==<!-- End sgen_feature_generalfeatures -->==			

h2. C Generator Features

==<!-- Start sgen_feature_ccodefeature -->==	

h4. CCodeFeature

The *CCodeFeature* feature allows to configure c code specific generator properties. It is an *optional* feature and consists of the following parameters:

# __InterfaceEventListener__ (Boolean, mandatory): generates listener interface for notification of outgoing events.
# __Singleton__ (Boolean, mandatory): generates a statically allocated singleton variant of the state machine that does not allow multiple instances.
# __DebugType__ (String, optional): don't use this property - it will be removed

Example configuration:

bc.. 
feature CCodeFeature {
	InterfaceEventListerner = true
	Singleton = true
}

p. ==<!-- End sgen_feature_ccodefeature -->==			

h2. Create Custom Code Generators

YAKINDU Statechart Tools provides a rich feature set to supports custom code generators out of the box. These code generators can be either written in Java, "Xtend":http://www.eclipse.org/xtend/ or in "Xpand":http://www.eclipse.org/modeling/m2t/?project=xpand
 
h3. Writing a custom code generator with Xtend2/Java

First, you have to create a new Xtend2 generator project. Click *File* > *New* > *Other...* > *YAKINDU* > *YAKINDU Xtend2/Java Generator Project* to create a new Xtend2 Generator Project. 

!images/xtendGenerator.png!

The wizards asks for a *Project name* and the name of the *Generator class*, where you have to specify a full qualified class name. If you check the *Use Xtend* checkbox, the Generator class will be initially created as an "Xtend":http://www.eclipse.org/xtend/ class. Otherwise, Java will be used for the generator.

The check box *Configure for Plugin Export* adds all required extension point registrations to the new project for exporting as a plugin The Generator Model can refer to the new Generator Plugin via its unique *Generator ID*. If you want to contribute custom generator features for your code generator, check the *Create Feature Library* check box.  

After click on *Finish* a new project is created in your workspace. All required plugin dependencies and extension points are registered and you can start to write your code generator based on the ExecutionFlow meta model [Link].

h3. Executing a custom Xtend2/Java code generator

YAKINDU Statechart Tools provide a convenient way to execute your generator while you are developing it.
Therefore, you have to create a new *Generator Model* with the generator id *yakindu::generic*, either by using the *New Statechart Generator Model* wizard or by simple creating a new text file with the file extension *.sgen*. the following feature allows to configure your code generator.

==<!-- Start sgen_feature_generator -->==

h4. Generator

The *Generator* feature allows the configuration of a custom code generator located in the workspace and written in Java or another JVM language. It is a *required* feature and consists of the following parameters:

# __generatorProject__  (String, required): The name of the generator project   
# __generatorClass__  (String, required): The full qualified class name of the code generator class.
# __configurationModule__ (String, optional): The full qualified class name for a guice module to configure the code generator 

Example configuration:

bc.. 
feature Generator {
	generatorProject = "org.yakindu.sct.mygenerator"
	generatorClass = "org.yakindu.sct.MyGenerator"
}
		
p. ==<!-- End sgen_feature_generator -->==

h3. Executing a custom Xpand code generator

to execute an xpand based custom code generator, you have to create a new *Generator Model* with the generator id *yakindu::xpand*, either by using the *New Statechart Generator Model* wizard or by simple creating a new text file with the file extension *.sgen*. the following feature allows to configure your code generator.

==<!-- Start sgen_feature_template -->==

h4. Template

The *Generator* feature allows the configuration of a custom code generator located in the workspace and written in Java or another JVM language. It is a *required* feature and consists of the following parameters:

# __templateProject__  (String, required): The name of the generator project   
# __templatePath__  (String, required): The full qualified template path to the main template.

Example configuration:

bc.. 
feature Template {
	templateProject = "ExampleProject"
	templatePath = "org::yakindu::sct::generator::xpand::Main::main"
}
p. ==<!-- End sgen_feature_template -->==