
p. 

==<div style="counter-reset: h1 7 h2 8">==

h2(#codegen_custom_code_generators). Custom code generators

Although YAKINDU Statechart Tools are shipped with powerful code generators for C, C++, and Java, it may be necessary to create a custom code generator to support a variety of use cases. One reason for a custom code generator could be to support additional programming languages – in this case we would be happy to receive a contribution! – or to generate code for an existing framework.

###. CHECK: Does YSCT provide code generators for C, C++, and Java.



h3(#codegen_prerequisits). Prerequisits

Implementing a custom code generator is no trivial task. Before you get started, you should have a basic understanding about the "Eclipse Modeling Framework":https://www.eclipse.org/modeling/emf/ that we are using to structure our data model. Furthermore, we highly recommend to use "Xtend":http://www.eclipse.org/xtend/ as your code generator's template language, although plain old Java is still supported. Xtend provides some great features like "Template Expressions":http://www.eclipse.org/xtend/documentation/203_xtend_expressions.html#templates, "Lambdas":http://www.eclipse.org/xtend/documentation/203_xtend_expressions.html#lambdas, and "Polymorphic Method Invocation":http://www.eclipse.org/xtend/documentation/202_xtend_classes_members.html#polymorphic-dispatch, boosting readability and productivity.

h3(#codegen_creating_a_new_custom_code_generator_project). Creating a new custom code generator project

Creating custom code generators is a built-in concept in YAKINDU Statechart Tools. You can develop custom code generators directly within your project workspace. You can choose between "Xtend2":http://www.eclipse.org/xtend/ (preferred) or Java for implementing the code generator templates.

To set up a new (Xtend2/Java) generator project, select _File → New → Other... → YAKINDU SCT_ → Xtend2/Java Generator Project_ and click _Next_.

!images/docu_xtendGenerator.png(Creating an Xtend2 generator project)!

p=. Creating an Xtend2 generator project

The wizard asks for a _Project name_ and the name of the _Generator class_, which has to be the fully-qualified class name. If you check the *Use Xtend* checkbox, the generator class will initially be 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 it 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. Click _Finish_ to close the wizard.

!images/docu_generatornavigator.png(Created generator project)!

p=. Created generator project

Voilà! The wizard creates a new generator project for you with a structure as shown above. The file _CustomGenerator.xtend_ contains a simple default code generator that simply prints the name of the statechart and all of its states to the target file.



h4(#codegen_executing_the_custom_code_generator). Executing the custom code generator

To test your custom code generator, create a new project containing a YAKINDU Statechart Tools model as described in section "&quot;Editing statecharts&quot;":../user-guide/editing_statecharts.html#edit_editing_statecharts.

After that, create a new generator model as described in section "&quot;Configuring a generator&quot;":../user-guide/code_generation_intro.html#codegen_configuring_a_generator. Select _Custom Xtend/Java based code generator_ as the generator to use. As you may have noticed, the generator model for the @yakindu::generic@ generator contains an additional feature called _Generator_. This is where you can specify the name of your custom generator project and the fully-qualified generator class name as shown below. 

bc(prettyprint).. 
GeneratorModel for yakindu::generic {
	statechart MyStatechart {
		feature Outlet {
			targetProject = "SCTExample"
			targetFolder = "src-gen"
		}
		feature Generator {
			generatorProject = "MyCustomGenerator"
			generatorClass = "org.yakindu.CustomGenerator"
		}
	}
}
p. When you right click the _.sgen_ file and select _Generate Statechart Artifacts_ from the context menu, the generator is executed and creates a new file _src-gen/MyStatechart.txt_ with the following contents:

bc(prettyprint).. 
The name of the Statemachine is 'MyStatechart'
The Statemachine has the following states:
main_region.A
main_region.B
p. Congratulations, you successfully created a custom generator project! Add 

bc. 
The Statemachine contains «flow.states.size» states

to the _CustomGenerator.xtend_ file and regenerate. The _MyStatechart.txt_ file will be updated immediately, a very powerful feature of YAKINDU Statechart Tools. You can develop your code generator at runtime with zero turnaround time. Just click _Generate_ and see the results.



h4(#codegen_sgen_features_for_custom_code_generators). SGen features for custom code generators

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

h5(#codegen_sgen_generator_feature). Generator feature

The *Generator* feature allows to configure a custom code generator located in the workspace and written in Java or in another JVM language.

It is a _required_ feature and has the following parameters:

* _generatorProject_ (String, required): Name of the generator project
* _generatorClass_ (String, required): Fully-qualified name of the code generator class

==<div class="example">==

Example:

bc. feature Generator {
    generatorProject = "org.yakindu.sct.mygenerator"
    generatorClass = "org.yakindu.sct.MyGenerator"
}

==</div>==

==<!-- End sgen_feature_generator -->==


h3(#codegen_different_meta_models_for_different_use_cases). Different meta models for different use cases

*The SGraph meta model*
The SGraph meta model defines the structural aspects of the statechart model and is similiar to the state machine model defined by the Unified Modeling Language (UML). The diagram below shows a simplified version:

!images/docu_sgraph_simple.png(Simplified SGraph meta model)!

p=. Simplified SGraph meta model

* *Statechart* extends __CompositeElement__, therefore it contains 0..* __Regions__. It is the root element of the model.
* *CompositeElement* is an abstract type that contains __Regions__. Known subclasses are __Statechart__ and __State__.
* *Region* contains 1..* __Vertices__.
* *Vertex* is an abstract type representing nodes in the SGraph tree. Vertices contain outgoing __Transitions__.
* *RegularState* is an abstract type derived from __Vertex__. It has no additional features, but it is the common base type for __State__ and __FinalState__.
* *State* is derived from __RegularState__ and __CompositeElement__, thus it may contain __Regions__ and __Transitions__.
* *FinalState* is derived from __RegularState__. It indicates the completion of its containing __Region__.
* *PseudoState* is an abstract type derived from __Vertex__. It has no additional features, but is the common base type for __Choice__, __Entry__, __Exit__ and __Synchronization__.
* *Choice* is a __Pseudostate__ with the additional attribute __kind__, that determines whether the element has __static__ or __dynamic__ execution semantics.
* *Entry* is a __Pseudostate__ with the additional attribute __kind__. An __Entry__ may be of the kind __Initial__, __ShallowHistory__ or __DeepHistory__.
* *Exit* is a __Pseudostate__. It is defined as the point where a region is left.
* *Synchronization* is a __Pseudostate__. It is equivalent to a __Fork__ and to a __Join__.
* *Transition* is defined as a directed relationship between two vertices.

==</div>==