1. Definition of metric and action functions

Now that we have understood the application logic, we can implement the metric and actuator functions. Our metric and action functions are very simple; they are defined in test/DeliveryWeb.lib.php. We have created an helper class lib/WebPager.php also: this class provides static methods which helps the programmer to create simple HTML user interface within her/his action functions.

In test/DeliveryWeb.lib.php we created two methods for each state: the metric function called <state_name> + Metric and the action function called <state_name> + Page (for example OrderPerformed state has the two functions orderPerformedMetric and orderPerformedPage). This is only a naming convention: what we have to rember is that the names of the functions defined in the Action elements of the automaton XML file must match those assigned to the DeliveryWeb class methods.

Talking about metric and action functions we can see that action functions don’t return any value at all, while metric functions return a string. This behavior is explicitly described in the automaton XML description file: for instance if we analyze the Action element related to OrderLine state metric function (a.k.a. orderLineMetric) we can see that its Enumeration child has Type attribute set to String and it also has three children which are Const elements. Each Const element has the Value attribute respectively set to “CANCEL_TASK”, “KO_CARR” and “PROCESSING”. These are the values that orderLineMetric can return and it is exactly what the related method code could possibly return.

Another important point deals with the input parameters of metric and action functions. Both these two function types receive (as first parameter) an associative array which represents the part of the environment which is “seen” by the function. We call the formal parameter $state in all functions but it may be called with another name. $state array is passed by reference for two reasons: first it is an efficient method to pass values to a method; second it allows metric or action functions to change their own environment in agreement with the language semantics. Notice that variables which belong to the environment of a metric or action functions have to be defined through their names in the sub-element Input related to each Action element with which each function is associated (see automaton XML file xml/DeliveryWeb.xml).

Moreover, we observe that action functions can receive a second parameter, conventionally named $debugInfo, which contains information about the actual state of the interpreter. This is useful during the application debugging phase (it looks like a so-called stack trace in conventional object-oriented languages, which contains debugging information related to a raised exceptions).

In this example each state is interactive. This means that each action function takes care of showing a proper graphic interface which allows users to insert the requested information and to perform the different tasks. As we have said before we have created an helper class, called WebPager (see lib/WebPager.php), which contains some static methods which are called by action functions. Below we describe the most important ones.

ClosePage method takes care of receiving debug information, if passed, and shows them at the bottom of the page.

Link and OpenForm methods concretely takes care of the jump mechanism of our automaton. In fact, for each interactive state the jump consists of a new GET or POST request respectively. Both methods take care of passing information about the current session:

1. the name of the session (session_name())
2. the identifier of the session (session_id())
3. the time of the request (given by microtime() function)

The names of the variables with which each above mentioned value is associated are defined by appropriate constants in test/WebInterpreter.php. Indeed these variable names represent a communication protocol between the programmer and the language interpreter. The time of the request, instead, helps the interpreter to rule out accidental page refreshes, that is when the user neither clicks on a link (state jump via a GET) nor sends a form (state jump via POST).

Following you can see the implementation of metric and action functions of Start state and how they are defined into the Action Pool.

   1 <?php
   2 
   3 require_once '../lib/WebPager.php';
   4 
   5 class DeliveryWeb {
   6     // State Start
   7     
   8     public function startPage(&$state, &$debugInfo=NULL)
   9     {
  10         WebPager::OpenPage("Delivery Web");
  11         WebPager::Title("Process Beginning");
  12         print "This is the introductive page. 
  13         This page may contain a login form.\n";
  14         print   "<ul><li>[".
  15                     WebPager::Link("START").
  16                 "]:<i>it simulates authentication operation</i>\n";
  17         print "</ul>\n";
  18         WebPager::ClosePage($debugInfo);
  19     }
  20     
  21     public function startMetric(&$state)
  22     {
  23         return "CREATE";
  24     }
  25     
  26     // Other States...    
  27 }
  28 ?>


 

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 
   3 <Automa xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   4     xsi:noNamespaceSchemaLocation="automa.xsd"
   5     Id="Delivery">
   6 <GlobalState>
   7 ...
   8 </GlobalState>
   9 <Clocks>
  10 ...
  11 </Clocks>
  12 <ActionPool>
  13 <!--  ACTIONS  -->
  14     <Action Id="startPage" Type="object">
  15         <Input>
  16             <Parameter Name="operator" />
  17             <Parameter Name="lineChosen" />
  18         </Input>
  19         <System Path="../test/DeliveryWeb.lib.php" 
  20             Class="DeliveryWeb"
  21             Name="startPage"/>
  22     </Action>
  23     ...
  24 <!--  METRICS  -->
  25     <Action Id="startMetric" Type="object">
  26         <Input>
  27             <Parameter Name="operator" />
  28             <Parameter Name="lineChosen" />
  29         </Input>
  30         <System Path="../test/DeliveryWeb.lib.php" 
  31             Class="DeliveryWeb"
  32             Name="startMetric" />
  33         <Enumeration Type="string">
  34             <Const Value="CREATE"/>
  35         </Enumeration>
  36     </Action>
  37     ...
  38 </ActionPool>
  39 <States>
  40     <State 
  41         Id="Start" IdAction="startPage"
  42         IdMetric="startMetric"
  43         Interactive="true">
  44         <ClockReset ClockVar="cStart"/>
  45     </State>
  46 </States>
  47 <FinalStates>
  48 </FinalStates>
  49 <InitialState IdState="Start"/>
  50 <Transitions>
  51     ...
  52 </Transitions>
  53 </Automa>

2. Starting XAL Interpreter

We have implemented metric and action functions so now we can build the entry point page where the XAL interpreter is called for executing our application.

   1 <?php
   2 
   3 /**
   4  * It is the entry point for a web-interactive automaton.
   5  * It cares about freezing the state of the automaton on
   6  * the session when an interactive state is met.
   7  */
   8 
   9 /**
  10  * The implementation of the WebIntepreter
  11  */
  12 require_once("../lib/WebInterpreter.php");
  13 
  14 $interpreter = new WebInterpreter("../xml/DeliveryWeb.xml");
  15 
  16 $interpreter->Run();
  17 
  18 ?>

Some source code comments:

• row 12: WebInterpreter class code is included. WebInterpreter is our XAL Interpreter implementation.
• row 14: a new instance of WebInterpreter is created: the argument passed to the constructor is automaton XML description file path (that is ../xml/DeliveryWeb.xml)
• row 16: the method Run of WebInterpreter class is called: this causes the execution of our XAL application