Abstract State Machine API Bundle

The Abstract State Machine API bundle provides a utility which represents a finite state machine. Such a state machine can be used for simulating the states and behavior of a specific device.

Contents:

Bundle Information

Bundle JAR
Import
Export

Overview
Defining a State Machine
- Only in Java by Using StateMachine
- In XML and Java by Using XMLStateMachine
  - Write the State Machine XML
  - Instantiate XMLStateMachine
Causing Transitions in the State Machine
Listening for Changes in a State Machine
References

Bundle Information

Bundle JAR

The JAR file of the Abstract State Machine API bundle is asm.jar, and resides in the bundles folder.

Import

The Abstract State Machine bundle imports the com.prosyst.util.xml package. It contains the ProSyst XML utility and is exported by the ProSyst Util Full Bundle.

Export

Package	Description
`com.prosyst.util.asm`	Contains an implementation of an Abstract State Machine, useful in the device simulators.
`com.prosyst.util.asm.xml`	Provides an additional facility to load the State Machine states, transitions and triggers from an XML file.

Overview

The Abstract State Machine can be used to define a state machine featuring the behavior of a specific device type. The Abstract State Machine consists of the following building elements:

States - Represent the states that a device can have. States are used to validate state machine's transitions.
Triggers - Represents actions or events which start specific transitions. Actions should be explicitly called while events are related to changes in a state machine's properties.
Transitions - Represent movement from one state to another. The Abstract State Machine defines two types of transitions:
- Internal transitions - An internal transition has only target state and no source state.
- Regular transitions - A regular transition has both source state and target state. It takes place only if the state machine's current state is the same as the transition's source state.
Properties - Used to verify guard conditions and track events. Additionally, properties can be used to store specific parameters in the state machine's context. Properties can be mapped to specific device variables.

The Abstract State Machine is represented by the com.prosyst.util.asm.StateMachine class. In addition, the com.prosyst.util.asm.xml.XMLStateMachine offers an Abstract State Machine modification which uses XML files for state machine definition.

Defining a State Machine

This section describes how to define a state machine by using StateMachine and by using XMLStateMachine.

To get more information on how to trigger changes in the state machine, refer to the "Causing Transitions in the State Machine" section.

Only in Java by Using StateMachine

Instantiate the StateMachine class.
Define states.
To define the states of your state machine, use the addState method as many times as the states are. A state machine must have an initial state - specify one of the already defined ones by using the setInitialState method.
Define properties.

To define a state machine property, use the setProperty method. This method can used further to change the property value which, if included in a trigger, may cause a state transition.

Define transitions.
Transitions are represented as Transition objects. To define a transition for your state machine, create a Transition instance and assign it name, target state and, if the transition is regular, source state.

If the transition will have a guard condition, use the setFilter method defining the condition as an LDAP-based org.osgi.framework.Filter on the value of a specific state machine property.

Tip: You can use the createFilter method of the BundleContext for your bundle to create a Filter from its String equivalent.
Define triggers.
1. To define an action trigger, use the addTriggerAction method providing the command's unique name and the transition that will be started when the triggering action is called.
2. To define an event trigger, use the addTriggerEvent method providing definition of the event condition as an LDAP-based Filter on a property's value and of the transition to take place when the event occurs.

Listing 1.1 contains the definition of a state machine of an abstract player device - from OFF it turned on to STANDBY. Next, when play is invoked, the state machine enters the PLAYING state from which it can go to PAUSED state or can return to STANDBY state. A guard condition for available tape is defined in the "play" transition. If the devices goes out of tape, an event trigger launches the transition from PLAYING to STANDBY state.

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.Filter;

import com.prosyst.util.asm.StateMachine;
import com.prosyst.util.asm.Transition;
 
public class MyStateMachine implements BundleActivator {

  // Constants for states
  final static String STATE_OFF = "OFF";
  final static String STATE_STANDBY = "STANDBY";
  final static String STATE_PLAY = "PLAYING";
  final static String STATE_PAUSE = "PAUSED";
  // Constants for action triggers
  final static String CMD_TURN_ON = "turnOn";
  final static String CMD_TURN_OFF = "turnOff";
  final static String CMD_PLAY = "play";
  final static String CMD_STOP = "stop";
  final static String CMD_PAUSE = "pause";
  
  StateMachine stateMachine = null;
  static String MORE_TAPE = "moreTape";
  // Defining the filter of the tape available condition
  static String TAPE_CONDITION = "(" + MORE_TAPE + "=true)";
  final static int TIMER_EVENT_TYPE = 8;

  // Method inherited from BundleActivator. It contains the definition of the state machine
  // and activates machine changes.
  public void start(BundleContext bc) throws Exception {

    stateMachine = new StateMachine();
    // Define states
    stateMachine.addState(STATE_OFF);
    stateMachine.addState(STATE_STANDBY);
    stateMachine.addState(STATE_PLAY);
    stateMachine.addState(STATE_PAUSE);
    stateMachine.setInitialState(STATE_OFF);
    // Define properties
    stateMachine.setProperty(MORE_TAPE, Boolean.FALSE);

    //Define transitions
    Transition turnOn = new Transition("turn on", STATE_OFF, STATE_STANDBY);
    Transition turnOff = new Transition("turn off", STATE_STANDBY, STATE_OFF);
    Transition play = new Transition("play", STATE_STANDBY, STATE_PLAY);

    Filter tapeFilter = bc.createFilter(TAPE_CONDITION);
    play.setFilter(tapeFilter);

    Transition stop = new Transition("stop", STATE_PLAY, STATE_STANDBY);
    Transition stopFromPause = new Transition("stop from pause", STATE_PAUSE, STATE_STANDBY);
    Transition pause = new Transition("pause", STATE_PLAY, STATE_PAUSE);
    Transition resume = new Transition("resume", STATE_PAUSE, STATE_PLAY);
    // Define triggers
    // Define action triggers
    stateMachine.addTriggerCommand(CMD_TURN_ON, turnOn);
    stateMachine.addTriggerCommand(CMD_TURN_OFF, turnOff);
    stateMachine.addTriggerCommand(CMD_PLAY, play);
    stateMachine.addTriggerCommand(CMD_PLAY, resume);
    stateMachine.addTriggerCommand(CMD_PAUSE, pause);
    stateMachine.addTriggerCommand(CMD_STOP, stop);
    stateMachine.addTriggerCommand(CMD_STOP, stopFromPause);

    // Define a filter defining an event for unavailable tape
    Filter noTapeFilter = bc.createFilter("(!" + TAPE_CONDITION + ")");
    // Define an event trigger activating the "stop" transition 
    //when the device goes out of tape
    stateMachine.addTriggerEvent(noTapeFilter, stop);

    // Initiate changes in the state machine
    . . .
  }

  // Method inherited from BundleActivator. 
  //Basically, removes the registered TimerListener and ungets the Timer service
  public void stop(BundleContext bc) {
    . . .
    stateMachine = null;
  }
}

Listing 1: A state machine based on StateMachine.

In XML and Java by Using XMLStateMachine

Write the State Machine XML

DTD.

DTD Element	Description
<!ELEMENT smc (states, props?, state-machine)>	Describes the state machine.
<!ELEMENT states (state+)>	Contains a list of state definitions.
<!ATTLIST states initial CDATA #REQUIRED>	The initial attribute of the <states> element defines the initial state of the state machine.
<!ELEMENT state (#PCDATA)>	Defines a state.
<!ELEMENT props (prop+)>	Contains additional custom properties of the state machine. Those properties can be initially loaded with some values.
<!ELEMENT prop EMPTY>	Specifies a single property.
<!ATTLIST prop name CDATA #REQUIRED value CDATA #IMPLIED>	Form the name of a property. The name attribute is required, but its value is optional. If the value attribute is set, the state machine will contain a property with the specified name and value as strings. If value is not set, then the state machine will assume that the record is set only to remind the developer what kind of properties are used within the state machine. These records are silently ignored.
<!ELEMENT state-machine (trigger+)>	Contains the state machine triggers, which are mapped to events and commands starting a given transition.
<!ELEMENT trigger (transition+)>	Defines a trigger associated with a "command" or "expr"(ession). In its body, the trigger includes at least one transition. When the trigger body contains many transitions, the first one that matches the current state and its guard condition is true is started.
<!ATTLIST trigger command CDATA #IMPLIED expr CDATA #IMPLIED>	The command is called by the developer. The expr(ession) is an LDAP filter that is checked upon property changes. A trigger can have either or both command and expr.
<!ELEMENT transition EMPTY>	Contains a transition definition.
<!ATTLIST transition name CDATA #REQUIRED toState CDATA #REQUIRED fromState CDATA #IMPLIED if CDATA #IMPLIED>	name - The transition's name fromState - The transition's source state. If not set, the transition is considered as internal. toState - The transition's target state. if - The transition's guard condition. If specified, this attribute should contain an LDAP string for the guard condition (see RFC 1960, "A String Representation of LDAP Search Filters"), which if matched successfully to the state machine properties, will allow execution of the transition.

Example State Machine XML. Listing 1.2 contains an XML equivalent of the "player" state machine from Listing 1.1.

<?xml version="1.0" encoding="iso-8859-1"?>
<smc>
  <states initial="OFF">
    <state>OFF</state>
    <state>STANDBY</state>
    <state>PLAYING</state>	       
    <state>PAUSED</state> 
  </states>
  <props>
    <prop name="moreTape" value="false"/>
  </props>
  <state-machine>
    <trigger command="turnOn">
      <transition name="turn on" fromState="OFF" toState="STANDBY"/>
    </trigger>
    <trigger command="turnOff">
      <transition name="turn off" fromState="STANDBY" toState="OFF"/>
    </trigger>
    <trigger command="play">
      <transition name="play" fromState="STANDBY" toState="PLAYING" if="(moreTape=true)"/>
      <transition name="resume" fromState="PAUSED" toState="PLAYING"/> 
    </trigger>	       
    <trigger command="pause">
      <transition name="pause" fromState="PLAYING" toState="PAUSED"/>
    </trigger>
    <trigger command="stop">
      <transition name="stop" fromState="PLAYING" toState="STANDBY"/>
      <transition name="stop from paused" fromState="PAUSED" toState="STANDBY"/>
	   </trigger>
    <trigger expr="(!(moreTape=true))">
      <transition name="stop" fromState="PLAYING" toState="STANDBY"/>
    </trigger>
  </state-machine>
</smc>

Listing 1.2: Defining a state machine in an XML.

Instantiate XMLStateMachine

To transfer the state machine components defined in an XML into a real state machine implementation, which can be mapped to a device's status and behavior, you should use the XMLStateMachine class.

Loading can be done when instantiating the XMLStateMachine class or at a later point by calling the load method. If you have used the no-argument constructor to create the XML state machine, besides the load method you should also provide the state machine with the BundleContext instance allocated for your bundle by invoking the setBundleContext method as the machine uses this BundleContext to create Filter objects for transition guard conditions and trigger events.

Listing 1.3 loads the state machine XML shown in Listing 1.2.

import java.io.IOException;
import java.io.InputStream;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

import com.prosyst.util.asm.xml.XMLStateMachine;

import com.prosyst.util.timer.TimerListener;

public class MyXmlStateMachine implements BundleActivator {
  XMLStateMachine stateMachine = null;

  // Method inherited from BundleActivator. It loads the definition of the state machine
  // and activates machine changes
  public void start(BundleContext bc) {
    InputStream in = MyXmlStateMachine.class.getResourceAsStream("/xml_machine.xml");
    try {
      stateMachine = new XMLStateMachine(in, bc);
      in.close();
    } catch (IOException e) {
      e.printStackTrace();
    } 
    // Initiate changes in the state machine 
    . . .
  }

  // Method inherited from BundleActivator
  public void stop(BundleContext bc) {
     . . .
    stateMachine = null;
  }
         
 }

Listing 1.3: Loading a state machine from an XML file.

Causing Transitions in the State Machine

This section provides information on calling the commands of a state machine thus causing transition from one state to another.

Calling an Action
If defined in the state machine, calling an action can trigger a state transition. To call such an action, use the call method on the corresponding state machine instance.
Changing a Property
Changing the value of a property can be done with the setProperty method. If the property is included in a transition guard condition, this condition can be satisfied or not and as a result the related transition will be executed or not. If the property is used in the definition of an event trigger, then depending on the property value the state machine can automatically enter into a specific state.

Listing 2 uses the "player" state machine previously defined (see Listing 1.x) and by calling actions and changing property values triggers state transitions. Basically, within regular time intervals of 20 seconds the example consecutively calls the actions "turn on", "play", "pause", and "play". While the player is playing, it is indicated that no more tape is available (setting "moreTape" to false) and the state machine automatically enters the STANDBY state.

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

import org.osgi.framework.ServiceReference;

import com.prosyst.util.asm.StateMachine;
 
import com.prosyst.util.timer.Timer;
import com.prosyst.util.timer.TimerListener;

public class MyStateMachine implements BundleActivator, TimerListener {

  StateMachine stateMachine = null;
  // Constant holding the property for available tape
  final static String MORE_TAPE = "moreTape";
  // Constants for action triggers
  final static String CMD_TURN_ON = "turnOn";
  final static String CMD_TURN_OFF = "turnOff";
  final static String CMD_PLAY = "play";
  final static String CMD_STOP = "stop";
  final static String CMD_PAUSE = "pause";

  // Variables related to the Timer service invocation
  String timerName = Timer.class.getName();
  Timer timer = null;
  ServiceReference timerRef = null;
  // Variable counting time notifications
  int counter = 0;
  // Variable indicating is this TimerListener is registered with the Timer service
  boolean timerRegistered = false;
  
   // Constant indicating the event type of received timer events
  final static int TIMER_EVENT_TYPE = 8;

  // Method inherited from BundleActivator. It contains the definition of the state machine
  // and activates machine changes.
  public void start(BundleContext bc) {
     // State machine definition
     . . .
    // Initiate changes in the state machine using notifications from the Timer service
    startChanges(bc);
  }

  // Method inherited from BundleActivator. 
  public void stop(BundleContext bc) {
    if (timerRegistered) {
      timer.removeListener(this, TIMER_EVENT_TYPE);
    }
    if (timerRef != null) {
      bc.ungetService(timerRef);
    }
      . . .
  }

  // Helper method which registers for timer notifications each 20 seconds.
  private void startChanges(BundleContext bc) {
    timerRef = bc.getServiceReference(timerName);
    if (timerRef != null) {
      timer = (Timer) bc.getService(timerRef);
      timer.addNotifyListener(this, Thread.NORM_PRIORITY,
                              Timer.PERIODICAL_TIMER, 20000, TIMER_EVENT_TYPE);
      timerRegistered = true;
    }
  }

  // Method inherited from TimerListener
  public void timer(int event) {
    if (event == TIMER_EVENT_TYPE) {
      if (stateMachine != null) {
        switch (counter) {
          case 0 : {
            // Call the "turn on" action
            stateMachine.call(CMD_TURN_ON);
            // Make tape available 
            stateMachine.setProperty(MORE_TAPE, Boolean.TRUE);
            counter++;
            break;
          }
          case 1 : {
            // Call the "play" action
            stateMachine.call(CMD_PLAY);
            counter++;
            break;
          }
          case 2 : {
            // Call the "pause" action
            stateMachine.call(CMD_PAUSE);
            counter++;
            break;
          }
          case 3 : {
            stateMachine.call(CMD_PLAY);
            counter++;
            break;
          }
          case 4 : {
            // Make tape unavailable.
            stateMachine.setProperty(MORE_TAPE, Boolean.FALSE);
            counter++;
            break;
          }
          case 5 : {
            // Unregister TimerListener
            timer.removeListener(this, TIMER_EVENT_TYPE);
            timerRegistered = false;
            break;
          }
        }
        // Printing the machine's state after each operation
        System.out.println("[My State Machine] Current state is "
                           + stateMachine.getCurrentState());
      }
    }
  }
}

Listing 2: Causing state transition in a state machine.

Listening for Changes in a State Machine

You can get notified about changes in a specific state machine instance, such as leaving and entering a particular state, executing a transition and changing a property value.

To receive such events, implement a com.prosyst.util.asm.StateMachineListener and register it in the target state machine by calling its setStateListener method.

References

Utility Bundles