Deep Java integration for state machines

Information: YAKINDU Statechart Tools Is Now itemis CREATE

Did you ever want to use a state machine in your Java code? Usually you would implement some switch-case statements over an enumeration or the more object-oriented state pattern. For larger state machines, this approach quickly gets hard to read and maintain. YAKINDU Statechart Tools (is now itemis CREATE) come with a graphical editor to model your statechart and to generate the corresponding Java code automatically for you.

However, up to now it was not possible to access Java code from within the graphical statechart, hence integrating the state machine code into your application code required quite some glue code. This is where our new feature, the deep Java integration, enters the stage.

Deep Java integration in YAKINDU Statechart Tools (is now itemis CREATE) allows you to directly access Java APIs in your statechart. Hence it facilitates an incorporation of state machine modeling in your Java development process. Currently, deep Java integration is work in progress. However, we just released a beta version containing the following features:

• You can import Java classes, interfaces and enums in your statechart and use them for your statechart variables.
• You can access all public and static members, like variables and methods, directly from the statechart. This avoids lots of boilerplate code.
• Java methods that are used in your statechart will be called during simulation. This avoids the cumbersome mocking of return values in the simulation process.

Use Java types for statechart variables

Deep Java integration is available for Java domain statecharts. You can select the Java domain in the statechart’s properties or when you create a new statechart.

A Java domain statechart uses a Java-oriented typesystem. You can use native Java types (like int) or their wrapper types (like java.lang.Integer) in variable declarations.

In addition, you can use the import statement to import Java classes, interfaces or enums. The content assist [Ctrl]+[Space] lists all classes that are on your project’s classpath. You can import classes from your JRE as well as your own ones.

Using Java types in your statechart also means that you can use generics, just as you would use them in your Java code.

import: "java.util.List"
import: "com.yakindu.sct.examples.musicplayer.java.Song"

internal:

var playList : List<Song>

The Java-oriented typesystem is able to infer generic type information. It emits errors in case types do not match. In that way, you can already avoid compilation errors before even generating any code.

Instantiation works slightly different than in Java. Instead of introducing the keyword new to our statechart language, constructors are transformed into static factory methods named new(…).

var playlist : List<Song> = ArrayList.new()

Accessing public members

Once you have a variable of a Java type, you can access all its public members, like methods or variables. Here again, the content assist gives you an overview of all accessible members, which contains all public instance as well as static class members.

Calling Java APIs during simulation

YAKINDU Statechart Tools (is now itemis CREATE) offer a built-in simulation for validating the behavior of your system even before generating any code. You can start the simulation in the context menu via Run → Run As → Statechart Simulation.

For Java domain statecharts, the simulation directly invokes the referenced Java methods. You can see the effects in the simulation view, where you can also manually change the values of accessible variables or raise events to see how your system reacts. You can also set breakpoints on states and transitions, just as if you were debugging your Java code.

Code generation and integration with client code

We have adapted the Java code generator that comes with the standard version of YAKINDU Statechart Tools (is now itemis CREATE) to also generate proper Java code for Java domain statecharts. To use the generated state machine code in your Java application, you basically need to implement the following steps:

private void setup() {
  // 1. Initialize state machine
  IPlayerStatemachine statemachine = new PlayerStatemachine();
  statemachine.init();
  
  // 2. Hook-up in-events
  playBtn.setOnAction((e) -> {
    statemachine.getSCInterface().raisePlayPressed();
  });
  stopBtn.setOnAction((e) -> {
    statemachine.getSCInterface().raiseStopPressed();
  });
  
  // 3. Hook-up out-events
  statemachine.getSCInterface().getListeners().add(new SCInterfaceListener() {
    
    @Override
    public void onPlayBtnEnabledRaised(boolean value) {
      playBtn.setDisable(!value);
    }
    
    @Override
    public void onStopBtnEnabledRaised(boolean value) {
      stopBtn.setDisable(!value);
    }
  });
  
  // 4. Run the state machine
  statemachine.enter();
}

We have added the full music player example to our example repository, which you can access from the example wizard (New → Example… → Statechart Example).

What’s next to come

One of the features that we already have in our pipeline is dependency injection. With dependency injection, you will be able to annotate your statechart variables with @Inject. This annotation will be reflected in the generated code, too. In that way, you can initialize the generated state machine by providing bindings for your variables.

We also plan to improve the simulation view to better reflect the information you need for evaluating your system. This means, for example, that you will see the contents of collection variables more easily.

Installation

Since the deep Java integration is not yet officially released, you need to add it manually to your YAKINDU Statechart Tools (is now itemis CREATE) installation. Please make sure you have the latest YAKINDU Statechart Tools (is now itemis CREATE) Professional Edition installed. In your running application, go to Help → Install New Software …, and select our release update site.

Under the Professional Edition category you will find the Java Domain (Beta) entry. Follow the wizard's instructions to complete the installation. Please note that you need a license for the Professional Edition to make the deep Java integration work. If you are using YAKINDU Statechart Tools (is now itemis CREATE) the first time, you will automatically receive a 1-month trial license. However, if you sign up for our beta testing programme, you will get 3 months for free!

Become a beta tester

If you are interested in trying out the deep Java integration feature, you can sign up for our beta testing program and receive the following benefits:

• Extended evaluation license for 3 months
• Take part in shaping this feature by giving meaningful feedback
• The best feedbacks will be honored with some goodies. ;)

Information: YAKINDU Statechart Tools Is Now itemis CREATE