Pauware presentation PauWare is a tool enabling to execute UML - - PDF document

Pauware​ ​presentation

PauWare is a tool enabling to execute UML state machines in plain Java programs. It is composed of two​ ​elements:

• An API defining a set of classes for building/programming a UML state machine associated

with​ ​business​ ​operations

• An​ ​execution​ ​engine​ ​that​ ​carries​ ​on​ ​events​ ​and​ ​executes​ ​the​ ​business​ ​operations

Pauware can be used with any Java platform. There exists a version for Java ME and Java EE, both compatible​ ​with​ ​Java​ ​SE,​ ​as​ ​well​ ​as​ ​a​ ​boilerplate​ ​code​ ​for​ ​Android​ ​or​ ​the​ ​NAO​ ​robot. Even if there exists a Pauware plugin for Netbeans, programing with the Pauware API can be done with​ ​any​ ​Java​ ​IDE​ ​as​ ​it​ ​requires​ ​only​ ​to​ ​import​ ​a​ ​JAR​ ​file.​ ​This​ ​file​ ​has​ ​a​ ​size​ ​of​ ​only​ ​100​ ​kB. This document makes a quick presentation of Pauware and shows its main features through concrete examples.

Guidelines

Programming with Pauware requires to think your code in a different way as the application execution will​ ​be​ ​event-driven.​ ​It​ ​is​ ​thus​ ​well-suited​ ​for​ ​reactive​ ​programming. The ultimate goal of an application is to execute business operations. The behavior of the application consists in defining when and why calling such business operations at a given point in time during the execution of the application. With Pauware, all this behavior is defined through a state machine and business​ ​operations​ ​are​ ​associated​ ​with​ ​states​ ​and​ ​transitions. To make the application evolving, i.e. executing it, there is a single thing to do: asking the state machine​ ​to​ ​process​ ​an​ ​event.​ ​This​ ​is​ ​simply​ ​done​ ​in​ ​this​ ​way: stateMachine.​run_to_completion​(​"myEventName"​); If, starting from the current active states, there exists transitions associated with this event, then the Pauware engine triggers the transitions and executes the business operations associated with the transitions​ ​and​ ​the​ ​target​ ​states. This​ ​way​ ​of​ ​programming​ ​has​ ​some​ ​consequences:

• In your code, you never directly call business operations: they will be called by the Pauware

execution​ ​engine.

• It is not possible to get the returned value of a business operation. You have to modify the

content​ ​of​ ​a​ ​shared​ ​object​ ​to​ ​get​ ​the​ ​result​ ​of​ ​the​ ​operation.

• If your business operations are taking parameters, there is a special (and not very intuitive)

way​ ​to​ ​specify​ ​them​ ​when​ ​calling​ ​business​ ​operations. 1

Apart from these points, there is nothing particular to respect or follow for implementing your application with Pauware: no naming convention, no interface to implement or class to extend. You can organize your code and your classes as you want. ​That is why Pauware is considered as an API rather​ ​than​ ​a​ ​framework.

Creation​ ​of​ ​the​ ​state​ ​machine

Java​ ​methods

Business operations or guards of transitions are implemented in standard Java methods. The Pauware engine will call them through reflection. The way to associate methods to states or transitions then follows​ ​the​ ​way​ ​the​ ​reflection​ ​mechanism​ ​of​ ​Java​ ​is​ ​running.​ ​It​ ​requires​ ​to​ ​set​ ​3​ ​values:

• The​ ​object​ ​on​ ​which​ ​the​ ​method​ ​has​ ​to​ ​be​ ​called
• The​ ​name​ ​of​ ​the​ ​method​ ​(a​ ​String​ ​value)
• The​ ​set​ ​of​ ​parameters​ ​under​ ​the​ ​form​ ​of​ ​an​ ​object​ ​array​ ​(Object[])

For​ ​instance,​ ​if​ ​you​ ​have​ ​a​ ​method​ ​with​ ​the​ ​signature public​​ ​void​​ ​doSomething​(​int​​ ​val) and​ ​you​ ​want​ ​that​ ​this​ ​method​ ​to​ ​be​ ​the​ ​activity​ ​of​ ​a​ ​state,​ ​you​ ​need​ ​to​ ​write: myState.​doActivity​(myObject,​ ​"doSomething"​,​ ​new​​ ​Object[]{​ ​45​​ ​}); In​ ​the​ ​following,​ ​it​ ​will​ ​be​ ​explained​ ​how​ ​to​ ​manage​ ​changing​ ​parameters.

States

The Pauware API enables to define states that can be primitive or composite, have parallel regions and history states (deep or shallow). Three business operations can be associated with a state: as entry, as its​ ​activity​ ​and​ ​as​ ​exit. The above state machine defines the behavior of a microwave oven. The two composite states specify if​ ​the​ ​door​ ​of​ ​the​ ​oven​ ​is​ ​open​ ​or​ ​closed. Here​ ​are​ ​some​ ​lines​ ​of​ ​code​ ​for​ ​building​ ​a​ ​part​ ​of​ ​the​ ​hierarchy​ ​of​ ​states: //​ ​The​ ​state​ ​off​ ​(of​ ​open)​ ​executes​ ​the​ ​"stop"​ ​method​ ​and //​ ​is​ ​the​ ​input​ ​state​ ​of​ ​its​ ​composite

• ffOpen​ ​=​ ​new​​ ​Statechart(​"Off"​);
• ffOpen.​set_entryAction​(mwb,​ ​"stop"​);
• ffOpen.​inputState​();

2

//​ ​The​ ​closed​ ​state​ ​is​ ​a​ ​composite​ ​containing​ ​the​ ​off​ ​and //​ ​baking​ ​states,has​ ​a​ ​deep​ ​history​ ​pseudo​ ​state​ ​and​ ​is //​ ​the​ ​input​ ​state​ ​of​ ​its​ ​composite​ ​(the​ ​state​ ​machine) closed​ ​=​ ​offClosed.​xor​(baking).​name​(​"Closed"​); closed.​deep_history​(); closed.​inputState​(); A composite state is built with the “xor” operator between several states. The “and” operator will build parallel regions. Please note that here the business operations are called on an object named “mwb”​ ​and​ ​have​ ​no​ ​parameter​ ​so​ ​the​ ​argument​ ​for​ ​the​ ​set​ ​of​ ​objects​ ​is​ ​optional. Creating​ ​the​ ​global​ ​state​ ​machine​ ​is​ ​made​ ​in​ ​the​ ​same​ ​way: stateMachine​ ​= ​ ​ ​ ​ ​ ​ ​new​​ ​Statechart_monitor​(closed.​xor​(open),​"Microwave"​,​ ​true​); The last parameter “true” aks the Pauware engine to write on the console information on what has appenning when processing an event (what are the active states, which transition has been triggered…).​ ​Put​ ​a​ ​“false”​ ​value​ ​to​ ​not​ ​get​ ​execution​ ​information​ ​on​ ​the​ ​console.

Transitions

If creating a hierarchy of states is easy and straightforward, adding transitions is a bit more complex. It consists in calling the “fires” method on a state machine instance but there are 12 variants (overloads) of this method depending on the information on the transition. It can be a bit confusing for the beginners and you can for instance think that you have associated a business operation with a transition​ ​but​ ​actually​ ​it​ ​is​ ​processed​ ​as​ ​a​ ​guard. There​ ​are​ ​3​ ​mandatory​ ​elements​ ​to​ ​set:

• The​ ​source​ ​state​ ​of​ ​the​ ​transition
• The​ ​target​ ​state​ ​of​ ​the​ ​transition
• The​ ​name​ ​of​ ​the​ ​event​ ​associated​ ​with​ ​the​ ​transition

Then,​ ​there​ ​are​ ​optional​ ​elements:

• A​ ​guard
• A​ ​business​ ​operation

Guards and business operations are implemented with standard Java methods. Methods for guards must​ ​return​ ​a​ ​boolean.​ ​The​ ​methods​ ​are​ ​set​ ​by:

• The​ ​object​ ​on​ ​which​ ​it​ ​will​ ​be​ ​called
• The​ ​name​ ​of​ ​the​ ​method
• An​ ​optional​ ​set​ ​of​ ​parameters​ ​(array​ ​of​ ​Object)

Here​ ​are​ ​for​ ​instance​ ​some​ ​lines​ ​for​ ​adding​ ​some​ ​transitions​ ​between​ ​states:

//​ ​From​ ​closed​ ​to​ ​open​ ​for​ ​the​ ​"DoorOpen"​ ​event​ ​with​ ​call //​ ​of​ ​the​ ​"openDoor"​ ​method

3

stateMachine.​fires​(​"DoorOpen"​,​ ​closed,​ ​open,​ ​true​,​ ​mwb,​ ​"openDoor"​); //​ ​From​ ​open​ ​to​ ​closed​ ​for​ ​the​ ​"DoorClosed"​ ​event​ ​with​ ​call //​ ​of​ ​the​ ​"closeDoor"​ ​method stateMachine.​fires​(​"DoorClosed"​,​ ​open,​ ​closed,​ ​true​,​ ​mwb,​ ​"closeDoor"​); //​ ​From​ ​off​ ​of​ ​closed​ ​to​ ​baking​ ​for​ ​the​ ​"Power"​ ​event stateMachine.​fires​(​"Power"​,​ ​offClosed,​ ​baking);

As the closed state has an history state, transitions leading to it will actually be on this history state and​ ​the​ ​last​ ​active​ ​state​ ​of​ ​the​ ​composite​ ​will​ ​be​ ​the​ ​concrete​ ​target​ ​of​ ​the​ ​transition.

Running​ ​the​ ​state​ ​machine

Once​ ​the​ ​state​ ​machine​ ​build,​ ​it​ ​is​ ​launched​ ​by​ ​simply​ ​calling​ ​the​ ​“start”​ ​method​ ​on​ ​it: stateMachine.​start​(); Now the Pauware engine is ready to process events. The “stop” method will stop the execution of the state​ ​machine. As said above, to make the application evolving, i.e. executing it, there is a single thing to do: asking the​ ​state​ ​machine​ ​to​ ​process​ ​an​ ​event.​ ​This​ ​is​ ​simply​ ​done​ ​in​ ​this​ ​way: stateMachine.​run_to_completion​(​"myEventName"​); If, starting from the current active states, there exists transitions associated with this event, then the Pauware engine triggers the transitions and executes the business operations associated with the transitions​ ​and​ ​the​ ​target​ ​states. “Run to completion” cycle means that the method is ending once everything that must executed has been executed. Concretely, that for all the triggered transitions, all the business operations associated with are finished, all the exit actions of previous active states and all the entry actions of the new active states are finished. There is an exception with the activity associated with a state: it is executed asynchronously​ ​in​ ​a​ ​dedicated​ ​thread.

Parameters​ ​of​ ​business​ ​operations​ ​or​ ​guards

If you have already had a look at the Pauware site and opened some examples, you have perhaps asked you the question: “but why are they defining several times the same transitions?”. It is because this​ ​is​ ​the​ ​-​ ​not​ ​really​ ​intuitive​ ​-​ ​way​ ​to​ ​change​ ​the​ ​parameters​ ​of​ ​a​ ​business​ ​operation​ ​or​ ​a​ ​guard. Let’s take a simple example: a state machine managing a Java stack (java.util.Stack). It has two states: “empty”​ ​and​ ​“not​ ​empty”​ ​depending​ ​if​ ​the​ ​stack​ ​is​ ​empty​ ​or​ ​not. The​ ​business​ ​operation​ ​for​ ​pushing​ ​a​ ​String​ ​in​ ​the​ ​stack​ ​is: 4

public​​ ​void​​ ​actionPush​(String​ ​value)​ ​{ System.​out​.​println​(​"-->​ ​push:​ ​"​+value); stack.​push​(value); } During​ ​the​ ​creation​ ​of​ ​the​ ​state​ ​machine,​ ​the​ ​following​ ​transitions​ ​are​ ​added: stateMachine.​fires​(​"push"​,​ ​empty,​ ​notEmpty,​ ​true​,​ ​this​, "actionPush"​,​ ​new​​ ​Object[]​ ​{​new​​ ​String()}); stateMachine.​fires​(​"push"​,​ ​notEmpty,​ ​notEmpty,​ ​true​,​ ​this​, "actionPush"​,​ ​new​​ ​Object[]​ ​{​new​​ ​String()}); For the event “push”, from “empty” to “not empty” state or from “not empty” state to itself, there is a transition that will call on the current object (this) the “actionPush” Java method taking a String as

• parameter. You can notice that the String objects contain nothing. It is not important here, the idea is

simply​ ​to​ ​set​ ​the​ ​signature​ ​of​ ​the​ ​method. Now, before processing the “push” event, it is required to redefine the transitions with the current value that has to be placed in the stack. A good practise for that is to define a method based on the name​ ​of​ ​the​ ​event: public​​ ​void​​ ​pushEvent​(String​ ​value)​ ​throws​​ ​Exception​ ​{ stateMachine.​fires​(​"push"​,​ ​empty,​ ​notEmpty,​ ​true​,​ ​this​, ​ ​"actionPush"​,​ ​new​​ ​Object[]​ ​{​ ​value​ ​}); stateMachine.​fires​(​"push"​,​ ​notEmpty,​ ​notEmpty,​ ​true​,​ ​this​, ​ ​"actionPush"​,​ ​new​​ ​Object[]​ ​{​ ​value​ ​}); stateMachine.​run_to_completion​(​"push"​); } The transitions have been redefined identically except for the parameter where we put here a concrete

• value. In practice, the transitions are not defined several times. The Pauware engine detects that the

same transition (same source and target states, same event, same operation or guard with same types

• f parameters on the same objects) exists already. Then, the parameters of the guard or the business
• peration​ ​are​ ​modified​ ​for​ ​the​ ​existing​ ​transition.

For modifying the business operations associated with states, you simply have to recall the “doActivity”,​ ​“[re]set_entryAction”​ ​or“[re]set_exitAction”​ ​with​ ​the​ ​new​ ​parameters​ ​to​ ​use.

Invariants

It is possible to add invariants to states. An invariant has for goal to check that the application and the state machine are running correctly. An invariant is a free Java method returning a boolean. It is set as for the other methods: an object on which the method is called, the name of the method and an

• ptional​ ​set​ ​of​ ​parameters​ ​under​ ​the​ ​form​ ​of​ ​an​ ​array​ ​of​ ​Object.

For instance, for the stack, we can add an invariant checking that in the “not empty” state, there is something​ ​in​ ​the​ ​stack. 5

First,​ ​we​ ​define​ ​the​ ​invariant: public​​ ​boolean​​ ​stackNotEmpty​()​ ​{ return​​ ​!​ ​stack.​isEmpty​(); } Then,​ ​we​ ​associate​ ​this​ ​invariant​ ​to​ ​the​ ​state​ ​when​ ​creating​ ​it: notEmpty​ ​=​ ​new​​ ​Statechart(​"Not​ ​Empty"​); notEmpty.​stateInvariant​(​this​,​ ​"stackNotEmpty"​); To check the invariants at runtime, it is required to ask explicitly to make it during the run to completion​ ​cycle.​ ​This​ ​is​ ​simply​ ​done​ ​in​ ​this​ ​way: stateMachine.​run_to_completion​(​"push"​, ​ ​AbstractStatechart_monitor.​Compute_invariants​); Currently, when an invariant is not respected, there is only an information written in the console if trace​ ​execution​ ​has​ ​been​ ​set​ ​on​ ​or​ ​by​ ​a​ ​red​ ​color​ ​in​ ​the​ ​state​ ​machine​ ​drawed​ ​by​ ​the​ ​Pauware​ ​viewer.

Pauware​ ​viewer

The Pauware viewer is a tool that graphically and automatically draws the state machine under execution in a Web browser. It is currently available as a Netbeans project. It has not be tested for

• ther IDE as Eclipse. The viewer is a prototype and is not real time (the screen refresh is made

between​ ​1​ ​and​ ​3​ ​seconds). Here is a screenshot of the viewer rendering for the microwave state machine. We can see, in blue, that​ ​the​ ​“Baking”​ ​state​ ​of​ ​“Closed”​ ​is​ ​active​ ​and​ ​that​ ​the​ ​previous​ ​active​ ​state​ ​was​ ​“Off”,​ ​in​ ​light​ ​grey. 6

Pauware​ ​enhancement

During​ ​the​ ​projet​ ​MegaM@RT,​ ​it​ ​is​ ​planned​ ​to​ ​enhance​ ​Pauware​ ​in​ ​the​ ​following​ ​way:

• Modification​ ​of​ ​the​ ​management​ ​of​ ​transitions​ ​for​ ​an​ ​easier​ ​use
• Pauware​ ​API​ ​code​ ​generator​ ​from​ ​UML​ ​diagrams​ ​or​ ​SC-XML​ ​specification
• Addition​ ​of​ ​a​ ​module​ ​for​ ​creating​ ​traces​ ​or​ ​logs​ ​during​ ​execution
• Verification​ ​features​ ​and​ ​better​ ​management​ ​of​ ​the​ ​invariants

7