How to Build Custom Generators for State Machines Easily 🚀

State machines, as they are used today in software projects, are an effective way of developing software for a lot of different applications. They have been used in the embedded systems domain to model reactive systems for decades. Highly-sophisticated tools, like Mathworks Stateflow and YAKINDU Statechart Tools, help embedded systems engineers to model and simulate the behavior of their systems and generate high-quality code out of the statechart models. 

In recent times, there has been a trend towards state machines for web applications. Frameworks, like XState and Spring Statemachine, support developers in using finite-state machines for front-end and back-end web development. Wouldn’t it be nice to reuse existing tools with all their modeling and simulation capabilities for modern web frameworks?

What you will learn in this article

This article is a step-by-step guide on how to develop custom code generators for YAKINDU Statechart Tools. All parts of YAKINDU Statecharts that we use throughout this article are open source. We will use Spring Statemachine as the target framework to explain the development of our custom code generator. And we will use Xtend — a flexible and expressive dialect of Java with a lot of features that are helpful for code generator development.

Grab your copy of YAKINDU Statechart Tools here, and let’s start coding!

Spring Statemachine Turnstile Example

Let’s have a look at a simple example and how it is written in Spring Statemachine. The turnstile example was taken from the Spring project example repository. It consists of two states, Locked and Unlocked. If the coin event is raised, the turnstile enters the Unlocked state, if the push event is raised, the turnstile goes back to the Locked state.

As you can see in the following code listing, only 29 lines of Java code are required to have a running example of the turnstile in Spring Statemachine.

@Configuration
@EnableStateMachine
public class TurnstileConfig
		extends EnumStateMachineConfigurerAdapter<States, Events> {

	public static enum States {
		LOCKED, UNLOCKED
	}

	public static enum Events {
		COIN, PUSH
	}

	@Override
	public void configure(StateMachineStateConfigurer<States, Events> states)
			throws Exception {
		states.withStates().initial(States.LOCKED)
				.states(EnumSet.allOf(States.class));
	}

	@Override
	public void configure(
			StateMachineTransitionConfigurer<States, Events> transitions)
			throws Exception {
		transitions.withExternal().source(States.LOCKED).target(States.UNLOCKED)
				.event(Events.COIN).and().withExternal().source(States.UNLOCKED)
				.target(States.LOCKED).event(Events.PUSH);
	}
}

The

TurnstileConfig 

@Configuration 

@EnableStatemachine

The

TurnstileConfig

EnumStateMachineConfigurerAdapter 

States 

Events 

configure 

They are used to define the States and connect them to each other via Transitions. All States are added to the states’ configuration, and the Locked state is marked to be the initial state of the state machine. The

configure 

In the next part, we will set up a new generator project and see how we can generate that code from our example model.

Creating the 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 Xtend or Java for implementing the code generator templates. Throughout this example, we will use Xtend as the programming language.

Xtend compiles into optimized, readable and pretty-printed Java code. Java and Xtend have a lot in common syntactically and semantically. Xtend is aimed to improve several aspects of Java and is especially useful when developing code generators.

Since the output is plain Java code, it is easily possible to integrate Xtend code with any existing Java library and vice versa.

Xtend is — like Java — a statically-typed language with the ability to infer variable and expression types in most cases. This slims down the code and increases its readability. Features that are useful for the development of code generators are extension methods, lambda expressions, dispatch functions and especially template expressions. Don’t worry — if you are familiar with Java you will learn Xtend in no time.

To set up a new generator project in YAKINDU Statechart Tools, we will use the generator template from our example wizard. So start up YAKINDU Statechart Tools and do the following:

• Select File → New- → Example. In the Wizard, select YAKINDU Statechart Examples and click Next.

• If it is the first time you use the example wizard, you have to click the Download button in order to load the latest examples from the Github repository.

• Next, select the Custom Generator Template from the menu on the left. Hit Install Dependencies and click Finish.Install Dependencies Directly From the Example Wizard

A background task is scheduled that will install some additional components into YAKINDU Statechart Tools. They are required for custom code generator development. Confirm the appearing dialog with Next. Accept the terms and conditions and click Install.

Once the installation is finished, a restart is required. That’s all you have to do to get started! 🎉 🎉

The custom code generator template

Let us have a look at the generated artifacts and their purpose. 

Since Xtend code compiles to Java code, there is a source folder called xtend-gen. It contains only generated resources and should therefore not be added to a version control systems like Git. The src folder contains the source code of our code generator.

YAKINDU Statechart Tools uses a dependency injection framework, Google Guice, to manage dependencies. All references to implementation types are handled in the

CustomGeneratorModule

CustomGenerator 

The code generator model is used to test our new code generator. When you right-click the turnstile.sgen file and select Generate Statechart Artifacts from the context menu, the generator is executed and creates a new file src-gen/turnstile.txt with the following contents:

The name of the state machine is 'turnstile'
I am a region main region
I am an entry of kind INITIAL
I am a state Locked
I am a state Unlocked

This is the default output of the initial generator. Congratulations, everything is set-up properly! 💪

The Custom Generator Template explained

As previously stated, the code that is responsible for the generated output is located in the

CustomGenerator 

class CustomGenerator implements ISGraphGenerator {

	override generate(Statechart sm, GeneratorEntry entry, IFileSystemAccess access) {
		access.generateFile(sm.name + '.txt', sm.generate.toString());
	}

	def dispatch String generate(Statechart it) {
		'''
			The name of the state machine is '«name»'
			«FOR Region region : regions»
				«region.generate»
			«ENDFOR»
		'''.toString
	}

	def dispatch String generate(Region it) {
		'''
			I am a region «name»
			«FOR state : vertices»
				«state.generate»
			«ENDFOR»
		'''
	}

	def dispatch String generate(State it) {
		'''
			I am a state «name»
			«FOR region : regions»
				«region.generate»
			«ENDFOR»
		'''
	}

	def dispatch String generate(Entry it) {
		'''
			I am an entry of kind «it.kind.toString»
		'''

	}
}

The

CustomGenerator 

ISGraphGenerator 

generate 

A Statechart contains zero or more Regions. A Region contains zero or more Vertices. A Vertex can be either of type State or of type Pseudostate. A Pseudostate is a state that can not be active — an Entry, Exit, Choice or Synchronization. If a State contains one or more Regions, it is called a Composite State.

The second parameter entry is of type GeneratorEntry and allows access to the code generator features of the turnstile.sgen generator model. 

The last parameter, access, is of tye IFileSystemAccess and can be used to write the result to the file system. It is a file system abstraction that is preconfigured with the target folders specified in the generator model. To create a new source file, the

generateFile 

The method

generate 

Xtend expressions are surrounded by so-called guillemets. They are evaluated at runtime. In our example, the result of the «name» expression will be Turnstile. Template expressions even allow control structures like FOR loops or IF statements.

We iterate over every Region and — again — call the generate method. Xtends dispatch keyword selects the suitable generate method depending on the runtime type of the argument.

Customizing for Spring Statemachine

Now that you are familiar with the basic language features lets have a look at how we can adopt this generic template to produce actual code for Spring Statemachine. Here is the example code that can handle basic features like States, Regions, Events, and Entries. 

/**
 * (c) 2019 by Andreas Muelder
 */
package org.yakindu.sct.generator.spring

import org.eclipse.xtext.generator.IFileSystemAccess
import org.yakindu.sct.generator.core.ISGraphGenerator
import org.yakindu.sct.model.sgen.GeneratorEntry
import org.yakindu.sct.model.sgraph.Entry
import org.yakindu.sct.model.sgraph.State
import org.yakindu.sct.model.sgraph.Statechart

class SpringGenerator implements ISGraphGenerator {

	override generate(Statechart statechart, GeneratorEntry entry, IFileSystemAccess access) {
		access.generateFile(statechart.name + "/" + statechart.name.toFirstUpper + 'Config.java', statechart.code);
	}

	def code(Statechart statechart) {
	'''
			package «statechart.name»;
		
			«statechart.imports»
			
			@Configuration
			@EnableStateMachine
			public class «statechart.name.toFirstUpper»Config
		        extends EnumStateMachineConfigurerAdapter<States, Events> {
			
				public static enum States {
				    «FOR state : statechart.regions.map[vertices].flatten.filter(State) SEPARATOR ','»
				    	«state.name.toUpperCase»
				    «ENDFOR»
				}
				
				public static enum Events {
				    «FOR event : statechart.scopes.map[events].flatten SEPARATOR ','»
				    	«event.name.toUpperCase»
				    «ENDFOR»
				}
				
				  @Override
				  public void configure(StateMachineStateConfigurer<States, Events> states)
				          throws Exception {
				      states
				          .withStates()
				              .initial(States.«statechart.initialState»)
				              .states(EnumSet.allOf(States.class));
				  }
			
			    @Override
			    public void configure(StateMachineTransitionConfigurer<States, Events> transitions)
			            throws Exception {
			    «FOR transition : statechart.regions.head.vertices.filter(State).map[outgoingTransitions].flatten BEFORE 'transitions' SEPARATOR '.and()' AFTER ';'»
			    	.withExternal()
			    	.source(States.«transition.source.name.toUpperCase»)
			    	.target(States.«transition.target.name.toUpperCase»)
			    	.event(Events.«transition.specification.toUpperCase»)
			    	«ENDFOR»
			    	}
				
				}
		'''
	}
	def protected initialState(Statechart it) {
		regions.head.vertices.filter(Entry).head.outgoingTransitions.head.target.name.toUpperCase
	}

	def protected imports(Statechart it) '''
		import java.util.EnumSet;
		import org.springframework.context.annotation.Configuration;
		import org.springframework.statemachine.config.EnableStateMachine;
		import org.springframework.statemachine.config.EnumStateMachineConfigurerAdapter;
		import org.springframework.statemachine.config.builders.StateMachineStateConfigurer;
		import org.springframework.statemachine.config.builders.StateMachineTransitionConfigurer;
		import «name».«name.toFirstUpper»Config.*;
	'''
}

The

code 

The first

configure 

configure 

This is everything you need to generate Spring Statemachine code for simple state machines. The full source code is available at GitHub. Do not forget to open a pull request if you’d like to provide additional features! 😃