Rolling the dice – part 1: Calling Java methods from state machines

Information: YAKINDU Statechart Tools Is Now itemis CREATE

YAKINDU Statechart Tools (now itemis CREATE) provide a versatile way for modeling and testing finite-state automata. However, what if you want to combine your state machine with some “outside” functionality? Something you want to make available to your statechart and use it from there? Or, what if you want to integrate your statechart as a component into another application?

In this two-article series, I am going to explain both these aspects. My programming language of choice is Java. However, using YAKINDU Statechart Tools (now itemis CREATE), you can do the same with C and C++.

The “dice throwing” scenario

The sample scenario that I am going to develop is throwing a dice. If a dice is rolled very often, all face values in the range of one to six should occur roughly with the same frequency. If you want to model that with a statechart, you’ll encounter the problem that the statechart language has no functionality for generating random values. Thus, the question arises where to get randomness from and how to make it available to the state machine.

Generating random values represents the general case of some business logic that is external to the statechart.

In principle, there are two different approaches to integrate a statechart with business logic:

• The business logic is available to the state machine, and the state machine actively calls it and uses its results.
• An application calls the business logic, hands the result over to the state machine, and observes what the state machine does.

We will model and implement both scenarios. Actually, they are quite similar. The external “business logic” is a Java method that upon each call generates a random number between one and six – something that is not possible in the statechart language.

In a first approach, we will call that Java method from within the statechart. In a second approach, we will write a little Java program that retrieves a random number and passes it to the statechart.

I am now going to develop the first scenario step by step.

Figure 1 shows a first version of the statechart. Its name is Dice_rolling, and it is located in a file called dice.sct. The statechart has a starting state Rolling_the_dice where we throw the dice. Depending on the result, we’ll transition to one of six successor states. Simple, isn’t it?

Figure 1. Initial statechart modeling dice throwing

The problem here is, of course, that the Rolling_the_dice state sets the faceValue to zero, not to any random value. This will cause the execution to get stuck, because there’s no transition leading away from that state as long as faceValue does not equal 1, 2, 3, 4, 5, or 6. In the YAKINDU Statechart Tools (now itemis CREATE) simulator, we can overcome this problem by manually modifying faceValue. If we set the variable to, say, 5, the guard condition [faceValue == 5] becomes true, and the state machine transitions to the D5 state.

Figure 2. Simulation result after manually setting the faceValue variable to 5

Manually setting variables is of course anything but a solution, even less for retrieving random numbers. Thus, our most urgent need is to implement the randomness functionality. In the Java programming language, this can be achieved easily. I will show the source code below, but before I can do so, we’ll first have to set up an appropriate development environment and "java-ify" our project.

Developing statecharts in a Java project

You can use YAKINDU Statechart Tools (now itemis CREATE) not only for developing statecharts, but also for developing Java applications as well as for developing both in combination. A requirement is, however, that you have to manage everything in a Java project. If you create your statecharts and your Java code in a Java project, they can play in concert.

To create a Java project, select File → New → Project … in the main menu, then select Java → Java Project. The Java project wizard prompts you to specify subdirectories for your Java sources and for the compiled binaries. By default, the folder names are src and bin.

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
    <name>my_plain_project</name>
    <comment></comment>
    <projects>
    </projects>
    <buildSpec>
    </buildSpec>
    <natures>
    </natures>
</projectDescription

<projectDescription>
    <name>my_plain_project</name>
    <comment></comment>
    <projects>
    </projects>
    <buildSpec>
        <buildCommand>
            <name>org.eclipse.xtext.ui.shared.xtextBuilder</name>
            <arguments>
            </arguments>
        </buildCommand>
    </buildSpec>
    <natures>
        <nature>org.eclipse.xtext.ui.shared.xtextNature</nature>
    </natures>
</projectDescription>

<<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
    <name>my_java_project</name>
    <comment></comment>
    <projects>
    </projects>
    <buildSpec>
        <buildCommand>
            <name>org.eclipse.jdt.core.javabuilder</name>
            <arguments>
            </arguments>
        </buildCommand>
    </buildSpec>
    <natures>
        <nature>org.eclipse.jdt.core.javanature</nature>
    </natures>
</projectDescription>

<projectDescription>
    <name>my_java_project</name>
    <comment></comment>
    <projects>
    </projects>
    <buildSpec>
        <buildCommand>
            <name>org.eclipse.xtext.ui.shared.xtextBuilder</name>
            <arguments>
            </arguments>
        </buildCommand>
        <buildCommand>
            <name>org.eclipse.jdt.core.javabuilder</name>
            <arguments>
            </arguments>
        </buildCommand>
    </buildSpec>
    <natures>
        <nature>org.eclipse.jdt.core.javanature</nature>
        <nature>org.eclipse.xtext.ui.shared.xtextNature</nature>
    </natures>
</projectDescription>

Creating random numbers in Java

Once we have set up a Java project, we can create a Java class containing the functionality we need. Right-click on the dice project in the project explorer and select New → Class in the context menu. In the New Java Class wizard, the source folder should be dice/src, which stands for the src folder in the dice project. Enter de.itemis.examples.dice as the package name (or whatever else you see fit) and Dice as the (class) name, then click on Finish. The Java file Dice.java is created and opened in an editor. Replace its default contents with the following source code:

package de.itemis.examples.dice;
import java.util.concurrent.ThreadLocalRandom;

public class Dice {

    public int dice() {
   	 final int MIN = 1;
   	 final int MAX = 6;
   	 return ThreadLocalRandom.current().nextInt(MIN, MAX + 1);
    }

}

The dice() method returns a random int value in the range of an ordinary dice each time it is called.

Connecting a Java method to a statechart

Now that we have implemented the Java method, let’s make it available to the statechart. This is achieved by declaring the Java method as an operation in the statechart’s definition section. The latter now looks as follows:

interface:
    var faceValue: integer
    operation dice(): integer

The operation’s signature must be exactly equivalent to the Java method’s signature, i.e., it must have the same name (here: dice), the same number and compatible types of parameters (here: none), and it must return a value of a compatible type (here: integer in the statechart, int in Java). 

In the Rolling_the_dice state, we change the entry action from faceValue = 0 to faceValue = dice(). That is, the state’s entry action calls the dice operation each time the state is entered.

Figure 3. A state calling a (Java) operation

Do we want to see that in action? Of course we do! However, if we run the statechart as a usual simulation, the execution flow still gets stuck in the Rolling_the_dice state. The reason is that we haven’t told the simulator yet where to find the dice() method. And if it doesn’t know that, the simulator instead uses a stub method that always returns 0.

Let’s change the run configuration and refer the simulator to the de.itemis.examples.dice.Dice class: Right-click on the dice.sct file in the project explorer view, and select Run As → Run Configurations … in the context menu. Enter the fully-qualified class name de.itemis.examples.dice.Dice into the operation class text field, then click on Run. Et voilá: The state machines passes the Rolling_the_dice state and ends up in one of the D… states. Re-run the statechart several times to observe that the D… state is indeed randomly chosen each time.

Rolling the dice over and over

The next step is to repeat throwing the dice in a loop. That means that after reaching one of the D… states, the execution flow should continue back to the Rolling_the_dice state, and everything is repeated over and over again.

I grouped the D… states into a composite state. This way, I only need a single transition from the Results state back to the Rolling_the_dice state – instead of six individual transitions. I also introduced counters for the possible face values. Each D… state now increments its corresponding counter, so that you can see how often each number came out as a result.

Figure 4. Repeatedly throwing the dice in a loop

When you start the simulation now, you can watch the D… states flicker briefly as the dice() operation returns their respective numbers. In the simulation view, you can also watch the count variables being incremented. You can (hopefully) also confirm that the counter values are indeed within the same order of magnitude.

You might wonder why execution is so slow. I mean, if your eyes can follow the state changes, execution isn’t fast. Well, that’s due to a default setting in YAKINDU Statechart Tools (now itemis CREATE)’ simulator: Unless you specify otherwise, the simulator executes the state machine in cycle-based mode and performs one run-to-completion step every 200 milliseconds only, i.e. only five per second.

If you want to speed things up, change the default of 200 ms by adding the @CycleBased annotation with a lower value, e.g., 50 ms, on a separate line at the top of the definition section: @CycleBased(50). You can even use @CycleBased(0), which will execute the state machine as fast as possible. Now you can no longer see the states changing. However the counter variables will update very fast now, subject to your hardware.

Now we have seen how we can call Java methods from a YAKINDU statechart, i.e., how to integrate Java functionality into a statechart. In the next part, I’ll explain how to do the integration the other way round, i.e., how to integrate a statechart into a Java program and make the latter use and control the statechart.

If you want to try YAKINDU Statechart Tools (now itemis CREATE) yourself in the meantime, get your free version here.

Information: YAKINDU Statechart Tools Is Now itemis CREATE