|
|
@@ -751,15 +751,12 @@ localEvent3 / NamedInterface.variable4 += 2.0; #2
|
|
|
<h2 id="APIspecificationsofthegeneratedcode">API specifications of the generated code</h2>
|
|
|
<p>In the following comments the TrafficLight example statemachine is used to describe the API specifications of the code generated by the Yakindu C and Java code generators. The following image shows the statechart. It is a model of a simple pedestrian crossing with a traffic light for pedestrians and a traffic light for the cars.</p>
|
|
|
<p>
|
|
|
- <img border="0" src="images/TrafficLight.png"/>
|
|
|
+ <img border="0" src="images/TrafficLight.png"/>
|
|
|
</p>
|
|
|
+ <h3 id="SpecificationsofJavacode">Specifications of Java code</h3>
|
|
|
<p>For Java you can checkout the project ‚org.yakindusct.examples.trafficlight’ from the Yakindu google code repository (
|
|
|
<a href="http://svn.codespot.com/a/eclipselabs.org/yakindu/SCT2/trunk/examples">Google code link</a> ). The Java example contains the statechart, sgen model, graphical widgets and some glue code to connect the generated code with the widgets. The graphical widgets are based on SWT. To execute the Java example you can run the file ‚CrossingDemoCycleBased.java’ as ‚Java Application’ from the eclipse ‚Run As’ context menu.
|
|
|
</p>
|
|
|
- <p>For C you can checkout the project ‚org.yakindu.examples.c.trafficlight’ from the Yakindu google code repository (
|
|
|
- <a href="http://svn.codespot.com/a/eclipselabs.org/yakindu/SCT2/trunk/examples">Google code link</a> ). The C example contains the statechart, sgen model, graphical widgets and some glue code to connect the generated code with the widgets. The graphical widgets are based on Qt. To execute the c example you can run the file org_yakindu_sct_examples_c_trafficlight as ‚Local C/C++ application’ from the eclipse ‚Run As’ context menu.
|
|
|
- </p>
|
|
|
- <h3 id="SpecificationsofJavacode">Specifications of Java code</h3>
|
|
|
<p>You find the generated code in the ‚src-gen’ folder of the traffic light example.</p>
|
|
|
<p>In the package ‚org.yakindu.sct.examples.trafficlight.cyclebased’ are the most basic statemachine interfaces and classes located. These are needed by each statemachine and are independend from the concrete statemachine design.</p>
|
|
|
<h4 id="InterfaceIStatemachine">Interface IStatemachine</h4>
|
|
|
@@ -806,8 +803,21 @@ public interface IStatemachine {
|
|
|
<code>exit()</code> method is used to leave a statemachine statefully. If for example a history state is used in one of the top regions the last active state is stored and the statemachine is leaved via
|
|
|
<code>exit()</code> and reentered via
|
|
|
<code>enter()</code> it continues working with this state. The
|
|
|
- <code>runCycle()</code> method is used to trigger a run to completion step in which the statemachine evaluates arising events and computes possible state changes.
|
|
|
+ <code>runCycle()</code> method is used to trigger a run to completion step in which the statemachine evaluates arising events and computes possible state changes. A run to completion step consists in a simplified view of the following steps:
|
|
|
</p>
|
|
|
+ <ul>
|
|
|
+ <li>Clear list of outgoing events.</li>
|
|
|
+ <li>Check whether events have occurred which lead to a state change</li>
|
|
|
+ <li>If a state change has to be done:
|
|
|
+ <ul>
|
|
|
+ <li>Execute exit actions of leaving state.</li>
|
|
|
+ <li>Save history state if necessary.</li>
|
|
|
+ <li>Set the new State active.</li>
|
|
|
+ <li>Execute entry action of the new state.</li>
|
|
|
+ </ul>
|
|
|
+ </li>
|
|
|
+ <li>Clear list of incoming events.</li>
|
|
|
+ </ul>
|
|
|
<h4 id="Timedstatemachines">Timed statemachines</h4>
|
|
|
<p>In the traffic light example timing is used (after clauses). To support this the interfaces ‚ITimedStatemachine’, ‚ITimerService’ and the class ‚TimeEvent’ are generated.</p>
|
|
|
<pre><code>package org.yakindu.sct.examples.trafficlight.cyclebased;
|
|
|
@@ -848,7 +858,7 @@ public interface ITimedStatemachine {
|
|
|
<code>TimeEvents</code>.
|
|
|
</p>
|
|
|
<p>Basically the correct handling of time has to be implemented by the developer because timer functions generally depend on the hardware target used. So for every hardware target a timer service class which implements the
|
|
|
- <code>ITimerService</code> Java interface has to be developed. Let’s have a look at the
|
|
|
+ <code>ITimerService</code> interface has to be developed. Let’s have a look at the
|
|
|
<code>ITimerService</code> interface:
|
|
|
</p>
|
|
|
<pre><code>package org.yakindu.sct.examples.trafficlight.cyclebased;
|
|
|
@@ -907,7 +917,7 @@ public interface ITimerService {
|
|
|
<code>TimeEvent</code> after the time is expired the method
|
|
|
<code>onTimeEventRaised(TimeEvent timeEvent)</code> has to be called on the statemachine (should be a
|
|
|
<code>ITimedStatemachine</code>). So the time event is recognized by the statemachine and will be processed by the next run cycle. You can conclude that the runtime environment has to call the statemachines ‚runCycle’ method as often as needed to process time events raised by the timing service as fast as possible. If you have in example a time event which should be raised by the timer service after 500 ms and the runtime environment only calls the statemachines
|
|
|
- <code>runCycle</code> method with a time period of 1000 ms the event could never be processed in the correct time.
|
|
|
+ <code>runCycle</code> method with a time period of 1000 ms the event could not be processed in the correct time.
|
|
|
</p>
|
|
|
<p>The parameter ‚cycleStartTime’ holds the absolute start time of the last run cycle. It can be used to reduce or remove the time offset used by the statemachines runtime operations to get a more precise timing behavior.</p>
|
|
|
<p>The method
|
|
|
@@ -1054,123 +1064,19 @@ public class TimerService implements ITimerService {
|
|
|
<p>To get a clue how to integrate the generated java statemachines into your existing projects have a look at the
|
|
|
<br/>
|
|
|
<code>CrossingDemoCycleBased</code> class and it’s abstract super class
|
|
|
- <code>CrossingDemoBase</code>:
|
|
|
+ <code>CrossingDemoBase</code>. The code starts with the main method in
|
|
|
+ <code>CrossingDemoCycleBased</code> class:
|
|
|
</p>
|
|
|
- <pre><code>package org.yakindu.sct.examples.java.trafficlight;
|
|
|
-
|
|
|
-import org.yakindu.sct.examples.trafficlight.cyclebased.RuntimeService;
|
|
|
-import org.yakindu.sct.examples.trafficlight.cyclebased.TimerService;
|
|
|
-import org.yakindu.sct.examples.trafficlight.cyclebased.trafficlightwaiting.TrafficLightWaitingStatemachine;
|
|
|
-
|
|
|
-/**
|
|
|
- * Example to show how to integrate the generated statemachine code into
|
|
|
- * existing projects.
|
|
|
- *
|
|
|
- * @author a.nyssen - initial API and implementation
|
|
|
- * @author m.muehlbrandt - adaptions to new statemachine code.
|
|
|
- * @author terfloth - refactoring
|
|
|
- */
|
|
|
-
|
|
|
-public class CrossingDemoCycleBased extends CrossingDemoBase {
|
|
|
-
|
|
|
- private TrafficLightWaitingStatemachine statemachine;
|
|
|
-
|
|
|
- public static void main(String[] args) {
|
|
|
-
|
|
|
- new CrossingDemoCycleBased().runTrafficLight();
|
|
|
- }
|
|
|
+ <pre><code>public static void main(String[] args) {
|
|
|
|
|
|
- @Override
|
|
|
- protected void setUpAndRunStatemachine() {
|
|
|
-
|
|
|
- statemachine = new TrafficLightWaitingStatemachine();
|
|
|
- statemachine.setTimerService(new TimerService());
|
|
|
- statemachine.enter();
|
|
|
-
|
|
|
- RuntimeService.getInstance().registerStatemachine(statemachine, 100);
|
|
|
- }
|
|
|
-
|
|
|
- @Override
|
|
|
- protected void tearDownStatemachine() {
|
|
|
- // End TimerHandler and RuntimeService.
|
|
|
- statemachine.getTimerService().cancel();
|
|
|
- RuntimeService.getInstance().cancelTimer();
|
|
|
- }
|
|
|
-
|
|
|
- @Override
|
|
|
- protected void readStatemachineOutput() {
|
|
|
- trafficLightFigure.setRed(statemachine.getSCITrafficLight()
|
|
|
- .getRed());
|
|
|
- trafficLightFigure.setYellow(statemachine.getSCITrafficLight()
|
|
|
- .getYellow());
|
|
|
- trafficLightFigure.setGreen(statemachine.getSCITrafficLight()
|
|
|
- .getGreen());
|
|
|
-
|
|
|
- pedestrianLightFigure.setWhite(statemachine.getSCIPedestrian()
|
|
|
- .getRequest());
|
|
|
- pedestrianLightFigure.setRed(statemachine.getSCIPedestrian()
|
|
|
- .getRed());
|
|
|
- pedestrianLightFigure.setGreen(statemachine.getSCIPedestrian()
|
|
|
- .getGreen());
|
|
|
- }
|
|
|
-
|
|
|
- @Override
|
|
|
- protected void pedestrianRequestButtonClicked() {
|
|
|
- statemachine.raisePedestrianRequest(); // raise event in statemachine
|
|
|
- }
|
|
|
-
|
|
|
- @Override
|
|
|
- protected void onOffButtonClicked() {
|
|
|
- statemachine.raiseOnOff(); // raise event in statemachine
|
|
|
- }
|
|
|
+ new CrossingDemoCycleBased().runTrafficLight();
|
|
|
}
|
|
|
|
|
|
</code></pre>
|
|
|
- <p></p>
|
|
|
- <pre><code>package org.yakindu.sct.examples.java.trafficlight;
|
|
|
-
|
|
|
-import org.eclipse.draw2d.FigureCanvas;
|
|
|
-import org.eclipse.draw2d.LightweightSystem;
|
|
|
-import org.eclipse.draw2d.geometry.Rectangle;
|
|
|
-import org.eclipse.swt.SWT;
|
|
|
-import org.eclipse.swt.layout.FillLayout;
|
|
|
-import org.eclipse.swt.layout.GridData;
|
|
|
-import org.eclipse.swt.layout.GridLayout;
|
|
|
-import org.eclipse.swt.widgets.Button;
|
|
|
-import org.eclipse.swt.widgets.Composite;
|
|
|
-import org.eclipse.swt.widgets.Display;
|
|
|
-import org.eclipse.swt.widgets.Listener;
|
|
|
-import org.eclipse.swt.widgets.Shell;
|
|
|
-
|
|
|
-/**
|
|
|
- * This class cares about setting up the UI of the pesestrian crossing and
|
|
|
- * delegates the state machine handling to the concrete subcasses.
|
|
|
- *
|
|
|
- * @author terfloth
|
|
|
- */
|
|
|
-public abstract class CrossingDemoBase {
|
|
|
-
|
|
|
- protected Shell shell;
|
|
|
- protected Display display;
|
|
|
- protected CrossingFigure crossing;
|
|
|
- protected TrafficLightFigure trafficLightFigure;
|
|
|
- protected PedestrianLightFigure pedestrianLightFigure;
|
|
|
-
|
|
|
- public CrossingDemoBase() {
|
|
|
- super();
|
|
|
- }
|
|
|
-
|
|
|
- protected abstract void setUpAndRunStatemachine();
|
|
|
-
|
|
|
- protected abstract void tearDownStatemachine();
|
|
|
-
|
|
|
- protected abstract void readStatemachineOutput();
|
|
|
-
|
|
|
- protected abstract void pedestrianRequestButtonClicked();
|
|
|
-
|
|
|
- protected abstract void onOffButtonClicked();
|
|
|
-
|
|
|
- public void runTrafficLight() {
|
|
|
+ <p>A new instance of the class is created and the method
|
|
|
+ <code>runTrafficLight()</code> is directly called. This method consist in the super class:
|
|
|
+ </p>
|
|
|
+ <pre><code>public void runTrafficLight() {
|
|
|
|
|
|
setUpAndRunStatemachine();
|
|
|
createUIContent();
|
|
|
@@ -1188,83 +1094,65 @@ public abstract class CrossingDemoBase {
|
|
|
}
|
|
|
|
|
|
tearDownStatemachine();
|
|
|
- }
|
|
|
-
|
|
|
- protected void createUIContent() {
|
|
|
- display = Display.getDefault();
|
|
|
- shell = new Shell(display);
|
|
|
- shell.setSize(400, 400);
|
|
|
- shell.setText("Traffic Light Demo");
|
|
|
- GridLayout shellLayout = new GridLayout();
|
|
|
- shellLayout.numColumns = 1;
|
|
|
- shell.setLayout(shellLayout);
|
|
|
-
|
|
|
- LightweightSystem lws = createLightweightsystem(shell);
|
|
|
- createButtonComposite(shell);
|
|
|
-
|
|
|
- crossing = new CrossingFigure();
|
|
|
- lws.setContents(crossing);
|
|
|
- trafficLightFigure = new TrafficLightFigure();
|
|
|
- crossing.add(trafficLightFigure);
|
|
|
- crossing.getLayoutManager().setConstraint(trafficLightFigure,
|
|
|
- new Rectangle(275, 75, 35, 90));
|
|
|
-
|
|
|
- pedestrianLightFigure = new PedestrianLightFigure();
|
|
|
- crossing.add(pedestrianLightFigure);
|
|
|
- crossing.getLayoutManager().setConstraint(pedestrianLightFigure,
|
|
|
- new Rectangle(50, 10, 70, 20));
|
|
|
- }
|
|
|
-
|
|
|
- protected LightweightSystem createLightweightsystem(Shell shell) {
|
|
|
-
|
|
|
- FigureCanvas canvas = new FigureCanvas(shell);
|
|
|
- GridData canvasGridData = new GridData();
|
|
|
- canvasGridData.horizontalAlignment = GridData.FILL;
|
|
|
- canvasGridData.verticalAlignment = GridData.FILL;
|
|
|
- canvasGridData.grabExcessVerticalSpace = true;
|
|
|
- canvasGridData.grabExcessHorizontalSpace = true;
|
|
|
- canvas.setLayoutData(canvasGridData);
|
|
|
- LightweightSystem lws = new LightweightSystem(canvas);
|
|
|
- return lws;
|
|
|
- }
|
|
|
-
|
|
|
- protected void createButtonComposite(Shell shell) {
|
|
|
- // create a composite to hold the buttons
|
|
|
- Composite buttonComposite = new Composite(shell, SWT.NO_SCROLL);
|
|
|
- GridData buttonCompositeGridData = new GridData();
|
|
|
- buttonCompositeGridData.horizontalAlignment = GridData.FILL;
|
|
|
- buttonCompositeGridData.grabExcessHorizontalSpace = true;
|
|
|
- buttonComposite.setLayoutData(buttonCompositeGridData);
|
|
|
- FillLayout buttonCompositeLayout = new FillLayout();
|
|
|
- buttonCompositeLayout.type = SWT.HORIZONTAL;
|
|
|
- buttonComposite.setLayout(new FillLayout());
|
|
|
-
|
|
|
- // create a button and event handlers
|
|
|
-
|
|
|
- Button pedestrianRequest = new Button(buttonComposite, SWT.PUSH);
|
|
|
- pedestrianRequest.setText("pedestrian request");
|
|
|
- pedestrianRequest.addListener(SWT.Selection, new Listener() {
|
|
|
- public void handleEvent(final org.eclipse.swt.widgets.Event event) {
|
|
|
- pedestrianRequestButtonClicked();
|
|
|
- }
|
|
|
+}
|
|
|
|
|
|
- });
|
|
|
+</code></pre>
|
|
|
+ <p>This method setups the statemachine and creates the UI content. In a while loop the content of the statemachine is read and the ui is repainted. If the ui shell is closed the loop is left and the statemachine is teared down. The really interresting methods are
|
|
|
+ <code>setUpAndRunStatemachine()</code>,
|
|
|
+ <code>readStatemachinOutput</code> and
|
|
|
+ <code>tearDownStatemachine()</code>:
|
|
|
+ </p>
|
|
|
+ <pre><code>protected void setUpAndRunStatemachine() {
|
|
|
|
|
|
- Button onOff = new Button(buttonComposite, SWT.PUSH);
|
|
|
- onOff.setText("on / off");
|
|
|
- onOff.addListener(SWT.Selection, new Listener() {
|
|
|
- public void handleEvent(final org.eclipse.swt.widgets.Event event) {
|
|
|
- onOffButtonClicked();
|
|
|
- }
|
|
|
+ statemachine = new TrafficLightWaitingStatemachine();
|
|
|
+ statemachine.setTimerService(new TimerService());
|
|
|
+ statemachine.init();
|
|
|
+ statemachine.enter();
|
|
|
+
|
|
|
+ RuntimeService.getInstance().registerStatemachine(statemachine, 100);
|
|
|
+}
|
|
|
|
|
|
- });
|
|
|
- }
|
|
|
+</code></pre>
|
|
|
+ <p>First a new instance of the generated statemachine is created. Because the traffic light statechart uses timing clauses the default implementation of the
|
|
|
+ <code>TimerService</code> is set. In the next steps the statemachine is initialized and entered. After the enter method ist executed the machine stays in a defined state. Finally the statemachine is passed to the runtime service. This service executes the
|
|
|
+ <code>runCycle()</code> method of the statemachine every 100 ms. So the statemachine executes a run to completion step every 100 ms.
|
|
|
+ </p>
|
|
|
+ <pre><code>protected void readStatemachineOutput() {
|
|
|
+ trafficLightFigure.setRed(statemachine.getSCITrafficLight()
|
|
|
+ .getRed());
|
|
|
+ trafficLightFigure.setYellow(statemachine.getSCITrafficLight()
|
|
|
+ .getYellow());
|
|
|
+ trafficLightFigure.setGreen(statemachine.getSCITrafficLight()
|
|
|
+ .getGreen());
|
|
|
+ pedestrianLightFigure.setWhite(statemachine.getSCIPedestrian()
|
|
|
+ .getRequest());
|
|
|
+ pedestrianLightFigure.setRed(statemachine.getSCIPedestrian()
|
|
|
+ .getRed());
|
|
|
+ pedestrianLightFigure.setGreen(statemachine.getSCIPedestrian()
|
|
|
+ .getGreen());
|
|
|
+}
|
|
|
|
|
|
+</code></pre>
|
|
|
+ <p>The generated code contains getters and setters for each variable and event. So it’s easy to read values from and write values to a statemachine or raise events and ask the statemachine if outgoing events were raised during the last run to completion step. Within
|
|
|
+ <code>readStatemachineOutput()</code> method these methods are used to read the light values from the statemachine and set them to the ui elements. Within the methods
|
|
|
+ <code>pedestrianRequestButtonClicked()</code> and
|
|
|
+ <code>onOffButtonClicked()</code> some events are raised.
|
|
|
+ </p>
|
|
|
+ <p>Hint:
|
|
|
+ <br/>If outgoing events are raised within the statemachine they remain active until the next run to completion step is started.
|
|
|
+ </p>
|
|
|
+ <pre><code>@Override
|
|
|
+protected void tearDownStatemachine() {
|
|
|
+ // End TimerHandler and RuntimeService.
|
|
|
+ statemachine.getTimerService().cancel();
|
|
|
+ RuntimeService.getInstance().cancelTimer();
|
|
|
}
|
|
|
|
|
|
</code></pre>
|
|
|
- <p>
|
|
|
- <br/>h3. Specifications of C code
|
|
|
+ <p>If the UI thread has been terminated by the user, the state machine will be shut down. It is necessary to end the timer service. Finally the runtime service is cancelled.</p>
|
|
|
+ <h3 id="SpecificationsofCcode">Specifications of C code</h3>
|
|
|
+ <p>For C you can checkout the project ‚org.yakindu.examples.c.trafficlight’ from the Yakindu google code repository (
|
|
|
+ <a href="http://svn.codespot.com/a/eclipselabs.org/yakindu/SCT2/trunk/examples">Google code link</a> ). The C example contains the statechart, sgen model, graphical widgets and some glue code to connect the generated code with the widgets. The graphical widgets are based on Qt. To execute the c example you can run the file org_yakindu_sct_examples_c_trafficlight as ‚Local C/C++ application’ from the eclipse ‚Run As’ context menu.
|
|
|
</p>
|
|
|
</body>
|
|
|
</html>
|
markus.muehlbrandt@gmail.com