simon
/
yakindu


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195
							<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
		<title>getting_started</title>
		<link type="text/css" rel="stylesheet" href="../style.css"/>
	</head>
	<body>
		<h1 id="Gettingstartedtutorial">Getting started</h1>
		<h3 id="Installation">Installation</h3>
		<p>For a new installation</p>
		<ul>
			<li>choose Eclipse menu Help/Install New Software ...</li>
			<li>press the &#8218;add&#8217; button in the top right corner of the installation wizard to add http://updates.yakindu.org/sct/kepler/releases as update site</li>
			<li>select all the listed features</li>
			<li>and follow the installation wizzard </li>
			<li>For updating the installed plugins select Help/Check for Updates...</li>
		</ul>
		<p>After installing the plugins a user guide is included in the Eclipse help. Choose Help/Help Contents from the menue. A browser window will pop up and you will find the user guide as an entry on the left side overview.</p>
		<p>When the installation finished the wizard will ask to reopen Eclipse. The restart is important to make the newly installed software work correctly.</p>
		<h3 id="Introduction" class="Tutorial">Introduction</h3>
		<p id="Tutorial">This tutorial will introduce the open source project Yakindu Statechart Tools (SCT).YAKINDU Statechart Tools provides an integrated modeling environment for the specification and development of reactive, event-driven systems based on the concept of statecharts. It is an easy to use tool that features sophisticated graphical state chart editing, validation and simulation of statecharts as well as code generation.</p>
		<p>In this tutorial you will learn how to create a new statechart model, execute it with the simulation engine and generate a fully working Java statechart implementation from it. Note that this tutorial will not explain statecharts in general, so you should familiarize yourself with the basic concepts of state machines first.
			<sup class="footnote">
				<a href="#___fn1">1</a>
			</sup> Before we get started, make sure you have Yakindu Statechart Tools properly installed. For installation instructions see chapter 
			<a href="getting_started.html">Installation</a> .
		</p>
		<h3 id="CallHandlingexampleexplained">CallHandling example explained</h3>
		<p id="Prepareaproject">The example application we will create during this tutorial is a system for handling of incoming phone calls. After start up, the system is in an Idle state and waits for incoming calls. If a call comes in, the user can either accept the call and open a connection or dismiss it. If the connection is opened, the system tracks the duration of the call and waits for the user to hang up. After hang up, the system displays the total time of call and returns to its idle state. The complete statechart model is shown below:</p>
		<p>
			<img class="img-rounded shadowed" border="0" src="images/example.png"/>
		</p>
		<h3 id="Prepareaproject">Prepare a project</h3>
		<p id="Createastatechartmodel">The first step is to create a new Project by choosing 
			<em>File -&gt; New -&gt; Project....</em> The dialog offers a couple of different project types. Since we want to generate Java code later on, choose 
			<em>Java -&gt; Java Project</em> from the wizard menu. Give the project a meaningful name, i.e. 
			<strong>CallHandling</strong> and click finish. It is good practice to separate your models from the source code. Therefore, create a new folder to the projects root by choosing 
			<em>File -&gt; New -&gt; Folder</em> from the projects context menu and call it 
			<strong>model</strong>.
		</p>
		<h3 id="Createastatechartmodel">Create a statechart model</h3>
		<p id="UsetheEditor">Next, create a new statechart model by choosing 
			<em>File -&gt; New -&gt; Other -&gt; Yakindu -&gt; YAKINDU Statechart Model</em>. The wizard asks for the parent folder and we choose 
			<strong>CallHandling/model</strong>. Name the File 
			<strong>CallHandling.sct</strong> and finish the wizard. Last, confirm the perspective switch with 
			<strong>Yes</strong>. The statechart editor opens and show the definition of a very simple statechart.
		</p>
		<h3 id="UsetheEditor">Use the Editor</h3>
		<p>YAKINDU statecharts are self-contained &#8211; they not only contain the definition of states and state transitions, but also the definition of the statechart interfaces. To define those interfaces, open the direct edit mode by double clicking onto the statechart definition block on the left and enter the following definition:</p>
		<pre class="prettyprint"><code>interface User:
in event accept_call
in event dismiss_call
</code></pre>
		<pre class="prettyprint"><code>interface Phone:
var duration : integer
in event incoming_call
</code></pre>
		<p>Tip:  The statechart Editor offers code completion for all textual parts. To open the content assist press 
			<strong>CTRL + space</strong>. For all keywords, a detailed description with example code shows up in the help hover besides the content assist window.
			<br/>
			<img border="0" src="images/ctrlspace.png"/> 
		</p>
		<p>The example code contains two interfaces and one internal block. The 
			<em>User</em> interface defines the communication of the system with the user. It consists of the two in events 
			<em>dismiss_call</em> and 
			<em>accept_call</em>. The 
			<em>Phone</em> interface defines the communication with the underlying hardware. It provides the in event 
			<em>incoming_call</em> as well as a variable 
			<em>duration</em> of type 
			<em>integer</em>.
		</p>
		<p>Next, give the initially created state the name 
			<strong>Idle</strong> by double clicking on the name label. The error marker will disappear. The validation of statecharts includes syntax and semantic checks of the complete statechart. Examples of validations are the detection of unreachable states, dead ends, and references to unknown events. These validation constraints are live checked during editing. In case a constraint is violated, this is visualized by warning and error markers, which are attached to the faulty model elements. By this the user gets direct and immediate feedback on the validation state of the statecharts
		</p>
		<p>Now, create the three states 
			<strong>Incoming Call</strong>, 
			<strong>Active Call</strong> and 
			<strong>Dismiss Call</strong> by dragging 
			<em>States</em> from the palette on the right onto the main region. Connect them with the 
			<em>Transition</em> tool from the palette as shown in the example model above. After each transition, select the appropriate event (use the content assist Ctrl + space to navigate from interfaces to events) in the direct editing pop up.
		</p>
		<p>Finally, create the internal behavior for the states 
			<strong>Active Call</strong> and 
			<strong>Dismiss Call</strong>. This can either be done by opening the direct editing text box via double click or using the property view on the bottom, that supports code completion, syntax highlighting and validation, too.
		</p>
		<p>If everything went well, there shouldn&#8217;t be any error markers and your example should look like the one in the following screenshot:</p>
		<p>
			<img class="img-rounded shadowed" border="0" src="images/example_final.png"/>
		</p>
		<p id="Simulatingthemodel">If something went wrong, you can still download the example project 
			<a href="examples/CallHandling.zip">here</a> . 
		</p>
		<h3 id="Simulatingthemodel">Simulating the model</h3>
		<p>To start the simulation, select your model in the project explorer on the left and select 
			<em>Run As -&gt; Yakindu Statechart</em> from the context menu. The perspective is switched from 
			<strong>SC Modeling</strong> to 
			<strong>SC Simulation</strong>. The simulation perspective defines two additional views. The 
			<em>Debug View</em> on the top shows all running statechart instances and allows the selection of one. Note that SCT allows multiple execution of one statechart as well as parallel execution of different statecharts at the same time. 
			<br/>The 
			<em>Simulation View</em> on the right allows raising of events and inspection and modification of variables. 
			<br/>When the simulation starts, the 
			<strong>Idle</strong> state becomes active since it is connected with the 
			<strong>Initial State</strong>. This is illustrated by a red foreground color in the editor. Now, raise a event by clicking on the 
			<em>incoming_call</em> hyperlink in the 
			<em>Simulation View</em> on the right. This will trigger a state transition from 
			<strong id="GenerateJavacode">Idle</strong> to 
			<strong>Incoming Call</strong>. Accept the call by raising the event 
			<em>accept_call</em>. State 
			<strong>Active Call</strong> becomes active and the value for duration in the 
			<em>Simulation View</em> increases every second. If you are done with your phone call, raise the 
			<em>dismiss_call</em> event. After 2 seconds, the system will return to its 
			<strong>Idle</strong> State.
			<br/>If your statechart behaves as expected, we can now go one step further and generate code out of it. Therefore, stop the simulation by pressing the 
			<em>Terminate</em> button from the toolbar on the top.
		</p>
		<h3 id="GenerateJavacode">Generate Java code</h3>
		<p>YAKINDU SCT includes code generators for Java and C out of the box. Our code generators follow a &#8222;code-only&#8221; approach and do not rely on any additional runtime library. The generated code provides a well-defined interface and can be integrated easily with any client code. In this tutorial we will generate Java code for our 
			<strong>CallHandling</strong> example.
		</p>
		<p>For code generation, SCT uses a textual generator model called SGen. This model allows customization of the code generation process. To create a new SGen model select the model folder in the project explorer on the left, and select 
			<em>New ��� Yakindu Statechart Generator Model</em> from the context menu. On the first wizard page, enter 
			<strong>CallHandling.sgen</strong> as the file name and press next. On the second wizard page, select 
			<em>Yakindu SCT Java Code Generator</em> from the drop down menu on the top. In the statechart tree below, check the 
			<strong>CallHandling.sct</strong> model and press Finish. The SGen Editor opens and show the following simple generator model:
		</p>
		<pre class="prettyprint"><code>GeneratorModel for yakindu::java {
	statechart CallHandling {
		feature Outlet {
			targetProject = "CallHandling"
			targetFolder = "src-gen"
		}
	}
}
</code></pre>
		<p>
			<em>yakindu::java</em>  is the unique ID of the code generator.  This is followed by a reference to our 
			<strong>CallHandling</strong> statechart model for that we want to generate code. Each statechart reference can contain different configuration features. The Outlet feature specifies the target project and folder for the generated artifacts.
		</p>
		<p>Since we are using timed events with our 
			<em>after</em> and 
			<em>every</em> expression, we want the generater to provide us a default implementation for the Timer Service. Therefore, we add the following feature to our generator model
		</p>
		<pre class="prettyprint"><code>feature GeneralFeatures {
	TimerService = true
}		
</code></pre>
		<p>The generator Model is executed by a builder. Thus, the artifacts are generated automatically if 
			<em>Project &gt; Build Automatically</em> is checked. If you want to execute your generator model manually, select 
			<em>Generate Statechart Artifacts</em> from the Package Explorer���s context menu.
		</p>
		<p id="Integrationwithclientcode">As a result, you should see a new folder 
			<strong>src-gen</strong> in your project explorer on the left that contains the generated java artifacts. Add the generated artifacts to the Java Build Path by selecting 
			<em>Build Path -&gt; Use as source folder</em> from the src-gen folders context menu. 
		</p>
		<h3 id="Integrationwithclientcode">Integration with client code</h3>
		<p>In the last step, we want to integrate the generated statechart implementation with some client code. Create a new class by selecting New -&gt; Class from the context menu of the src folder in the project explorer. Give it a meaningful name, for example CallHandlingClient and hit finish.
			<br/> Next, copy the following code into your created class. 
		</p>
		<pre class="prettyprint linenums"><code>1  import org.yakindu.scr.TimerService;
2  import org.yakindu.scr.callhandling.CallHandlingStatemachine;
3  public class CallHandlingClient {
4        public static void main(String[] args) throws Exception {
5               CallHandlingStatemachine sm = new CallHandlingStatemachine();
6               sm.setTimerService(new TimerService());
7               // enter the sm and active the Idle state
8               sm.enter();
9               // Raise an incoming call
10              sm.getSCIPhone().raiseIncoming_call();
11              sm.runCycle();
12              // Accept the call
13              sm.getSCIUser().raiseAccept_call();
14              sm.runCycle();
15              for (int i = 0; i &lt; 50; i++) {
16                      Thread.sleep(200);
17                      sm.runCycle();
18              }
19              System.out.println(String.format("The phone call took %d s", +sm
20                              .getSCIPhone().getDuration()));
21              sm.getSCIUser().raiseDismiss_call();
22              sm.runCycle();
23        }
24  }
</code></pre>
		<p>Let&#8217;s have a detailed look at the implementation. First, create a new instanceof your Statemachine by calling the default constructor. (line 5). Since we use timed events, the statechart implementation requires an implementation of ITimerService. Because of the TimerService feature that we added to the genmodel, the code generator creates default implementation that uses the java.util.Timer. We create a new instanceof of the default TimerService and set it to the statemachine. (line 6). The call of the enter method in line 8 enteres the statechart and activates the Idle state. For each interface created in the statechart specification block, a getter for this interface is generated. (getSCIPhone() and getSCIUser()). You can access all in events and variables via these interfaces. In line 10, the incoming call event is raised, that activates the Incoming Call state after the next runcycle is executed. (line 11). In line 13, we raise the accept call event via the user interface, that activates the Active Call State after the next runcycle. (line 17). From line 15 to line 18, the runcycle is executed periodically every 200ms. After that, the duration is printed to console. (line 19, 20). Finally, the event dismiss call is executed that activated the 
			<strong id="Weblinks">Dimiss Call</strong> state after the next runcycle. 
		</p>
		<p>Finally, execute the code via Run As -&gt; Java Application from the context menu. </p>
		<h2 id="Overview">Weblinks</h2>
		<p id="___fn1" class="footnote">
			<sup>1</sup> 
			<a href="http://en.wikipedia.org/wiki/UML_state_machine">UML Statemachines</a>
		</p>
	</body>
</html>