jade.core.behaviours
Class FSMBehaviour

java.lang.Object
  |
  +--jade.core.behaviours.Behaviour
        |
        +--jade.core.behaviours.CompositeBehaviour
              |
              +--jade.core.behaviours.SerialBehaviour
                    |
                    +--jade.core.behaviours.FSMBehaviour
All Implemented Interfaces:
java.io.Serializable, Serializable
Direct Known Subclasses:
AchieveREResponder, HandlerSelector, jade.proto.Initiator, ProposeInitiator, ProposeResponder, jade.proto.Responder, jade.proto.SSResponder, SubscriptionResponder, TwoPhInitiator

public class FSMBehaviour
extends SerialBehaviour

Composite behaviour with Finite State Machine based children scheduling. It is a CompositeBehaviour that executes its children behaviours according to a FSM defined by the user. More specifically each child represents a state in the FSM. The class provides methods to register states (sub-behaviours) and transitions that defines how sub-behaviours will be scheduled.

At a minimum, the following steps are needed in order to properly define a FSMBehaviour:

A number of other methods are available in this class for generic tasks, such as getting the current state or the name of a state, ...

Version:
$Date: 2005-11-10 10:37:54 +0100 (Thu, 10 Nov 2005) $ $Revision: 5819 $
Author:
Giovanni Caire - CSELT
See Also:
SequentialBehaviour, ParallelBehaviour, Serialized Form

Field Summary
protected  java.lang.String currentName
           
protected  List lastStates
           
protected  java.lang.String previousName
           
 
Fields inherited from class jade.core.behaviours.Behaviour
myAgent
 
Constructor Summary
FSMBehaviour()
          Default constructor, does not set the owner agent.
FSMBehaviour(Agent a)
          This constructor sets the owner agent.
 
Method Summary
protected  boolean checkTermination(boolean currentDone, int currentResult)
          Check whether this FSMBehaviour must terminate.
 Behaviour deregisterState(java.lang.String name)
          Deregister a state of this FSMBehaviour.
protected  void forceTransitionTo(java.lang.String next)
          Temporarily disregards the FSM structure, and jumps to the given state.
 Collection getChildren()
          Return a Collection view of the children of this SequentialBehaviour
protected  Behaviour getCurrent()
          Get the current child
 int getLastExitValue()
          Retrieve the exit value of the most recently executed child.
 java.lang.String getName(Behaviour state)
          Retrieve the name of the FSM state associated to the given child behaviour.
protected  Behaviour getPrevious()
          Get the previously executed child
 Behaviour getState(java.lang.String name)
          Retrieve the child behaviour associated to the FSM state with the given name.
protected  void handleInconsistentFSM(java.lang.String current, int event)
           
protected  void handleStateEntered(Behaviour state)
           
 int onEnd()
          Override the onEnd() method to return the exit value of the last executed state.
 void registerDefaultTransition(java.lang.String s1, java.lang.String s2)
          Register a default transition in the FSM defining the policy for children scheduling of this FSMBehaviour.
 void registerDefaultTransition(java.lang.String s1, java.lang.String s2, java.lang.String[] toBeReset)
          Register a default transition in the FSM defining the policy for children scheduling of this FSMBehaviour.
 void registerFirstState(Behaviour state, java.lang.String name)
          Register a Behaviour as the initial state of this FSMBehaviour.
 void registerLastState(Behaviour state, java.lang.String name)
          Register a Behaviour as a final state of this FSMBehaviour.
 void registerState(Behaviour state, java.lang.String name)
          Register a Behaviour as a state of this FSMBehaviour.
 void registerTransition(java.lang.String s1, java.lang.String s2, int event)
          Register a transition in the FSM defining the policy for children scheduling of this FSMBehaviour.
 void registerTransition(java.lang.String s1, java.lang.String s2, int event, java.lang.String[] toBeReset)
          Register a transition in the FSM defining the policy for children scheduling of this FSMBehaviour.
 void reset()
          Put this FSMBehaviour back in the initial condition.
 void resetStates(java.lang.String[] states)
          Reset the children behaviours registered in the states indicated in the states parameter.
protected  void scheduleFirst()
          Prepare the first child for execution.
protected  void scheduleNext(boolean currentDone, int currentResult)
          This method schedules the next child to be executed.
 
Methods inherited from class jade.core.behaviours.CompositeBehaviour
action, block, done, resetChildren, restart, setAgent
 
Methods inherited from class jade.core.behaviours.Behaviour
block, getBehaviourName, getDataStore, getParent, isRunnable, onStart, root, setBehaviourName, setDataStore
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

lastStates

protected List lastStates

currentName

protected java.lang.String currentName

previousName

protected java.lang.String previousName
Constructor Detail

FSMBehaviour

public FSMBehaviour()
Default constructor, does not set the owner agent.


FSMBehaviour

public FSMBehaviour(Agent a)
This constructor sets the owner agent.

Parameters:
a - The agent this behaviour belongs to.
Method Detail

registerState

public void registerState(Behaviour state,
                          java.lang.String name)
Register a Behaviour as a state of this FSMBehaviour. When the FSM reaches this state the registered Behaviour will be executed.

Parameters:
state - The Behaviour representing the state
name - The name identifying the state.

registerFirstState

public void registerFirstState(Behaviour state,
                               java.lang.String name)
Register a Behaviour as the initial state of this FSMBehaviour.

Parameters:
state - The Behaviour representing the state
name - The name identifying the state.

registerLastState

public void registerLastState(Behaviour state,
                              java.lang.String name)
Register a Behaviour as a final state of this FSMBehaviour. When the FSM reaches this state the registered Behaviour will be executed and, when completed, the FSMBehaviour will terminate too.

Parameters:
state - The Behaviour representing the state
name - The name identifying the state.

deregisterState

public Behaviour deregisterState(java.lang.String name)
Deregister a state of this FSMBehaviour.

Parameters:
name - The name of the state to be deregistered.
Returns:
the Behaviour if any that was registered as the deregistered state.

registerTransition

public void registerTransition(java.lang.String s1,
                               java.lang.String s2,
                               int event)
Register a transition in the FSM defining the policy for children scheduling of this FSMBehaviour.

Parameters:
s1 - The name of the state this transition starts from
s2 - The name of the state this transition leads to
event - The termination event that fires this transition as returned by the onEnd() method of the Behaviour representing state s1.
See Also:
Behaviour.onEnd()

registerTransition

public void registerTransition(java.lang.String s1,
                               java.lang.String s2,
                               int event,
                               java.lang.String[] toBeReset)
Register a transition in the FSM defining the policy for children scheduling of this FSMBehaviour. When this transition is fired the states indicated in the toBeReset parameter are reset. This is particularly useful for transitions that lead to states that have already been visited.

Parameters:
s1 - The name of the state this transition starts from
s2 - The name of the state this transition leads to
event - The termination event that fires this transition as returned by the onEnd() method of the Behaviour representing state s1.
toBeReset - An array of strings including the names of the states to be reset.
See Also:
Behaviour.onEnd()

registerDefaultTransition

public void registerDefaultTransition(java.lang.String s1,
                                      java.lang.String s2)
Register a default transition in the FSM defining the policy for children scheduling of this FSMBehaviour. This transition will be fired when state s1 terminates with an event that is not explicitly associated to any transition.

Parameters:
s1 - The name of the state this transition starts from
s2 - The name of the state this transition leads to

registerDefaultTransition

public void registerDefaultTransition(java.lang.String s1,
                                      java.lang.String s2,
                                      java.lang.String[] toBeReset)
Register a default transition in the FSM defining the policy for children scheduling of this FSMBehaviour. This transition will be fired when state s1 terminates with an event that is not explicitly associated to any transition. When this transition is fired the states indicated in the toBeReset parameter are reset. This is particularly useful for transitions that lead to states that have already been visited.

Parameters:
s1 - The name of the state this transition starts from
s2 - The name of the state this transition leads to
toBeReset - An array of strings including the names of the states to be reset.

getState

public Behaviour getState(java.lang.String name)
Retrieve the child behaviour associated to the FSM state with the given name.

Returns:
the Behaviour representing the state whose name is name, or null if no such behaviour exists.

getName

public java.lang.String getName(Behaviour state)
Retrieve the name of the FSM state associated to the given child behaviour.

Returns:
the name of the state represented by Behaviour state, or null if the given behaviour is not a child of this FSM behaviour.

getLastExitValue

public int getLastExitValue()
Retrieve the exit value of the most recently executed child. This is also the trigger value that selects the next FSM transition.

Returns:
the exit value of the last executed state.

onEnd

public int onEnd()
Override the onEnd() method to return the exit value of the last executed state.

Overrides:
onEnd in class Behaviour
Returns:
an integer code representing the termination value of the behaviour.

scheduleFirst

protected void scheduleFirst()
Prepare the first child for execution. The first child is the Behaviour registered as the first state of this FSMBehaviour

Specified by:
scheduleFirst in class CompositeBehaviour
See Also:
CompositeBehaviour.scheduleFirst()

scheduleNext

protected void scheduleNext(boolean currentDone,
                            int currentResult)
This method schedules the next child to be executed. It checks whether the current child is completed and, in this case, fires a suitable transition (according to the termination event of the current child) and schedules the child representing the new state.

Specified by:
scheduleNext in class CompositeBehaviour
Parameters:
currentDone - a flag indicating whether the just executed child has completed or not.
currentResult - the termination value (as returned by onEnd()) of the just executed child in the case this child has completed (otherwise this parameter is meaningless)
See Also:
CompositeBehaviour.scheduleNext(boolean, int)

handleInconsistentFSM

protected void handleInconsistentFSM(java.lang.String current,
                                     int event)

handleStateEntered

protected void handleStateEntered(Behaviour state)

checkTermination

protected boolean checkTermination(boolean currentDone,
                                   int currentResult)
Check whether this FSMBehaviour must terminate.

Specified by:
checkTermination in class CompositeBehaviour
Parameters:
currentDone - a flag indicating whether the just executed child has completed or not.
currentResult - the termination value (as returned by onEnd()) of the just executed child in the case this child has completed (otherwise this parameter is meaningless)
Returns:
true when the last child has terminated and it represents a final state. false otherwise
See Also:
CompositeBehaviour.checkTermination(boolean, int)

getCurrent

protected Behaviour getCurrent()
Get the current child

Specified by:
getCurrent in class CompositeBehaviour
See Also:
CompositeBehaviour.getCurrent()

getChildren

public Collection getChildren()
Return a Collection view of the children of this SequentialBehaviour

Specified by:
getChildren in class CompositeBehaviour
See Also:
CompositeBehaviour.getChildren()

forceTransitionTo

protected void forceTransitionTo(java.lang.String next)
Temporarily disregards the FSM structure, and jumps to the given state. This method acts as a sort of GOTO statement between states, and replaces the currently active state without considering the trigger event or whether a transition was registered. It should be used only to handle exceptional conditions, if default transitions are not effective enough.

Parameters:
next - The name of the state to jump to at the next FSM cheduling quantum. If the FSM has no state with the given name, this method does nothing.

getPrevious

protected Behaviour getPrevious()
Get the previously executed child

See Also:
CompositeBehaviour.getCurrent()

reset

public void reset()
Put this FSMBehaviour back in the initial condition.

Overrides:
reset in class CompositeBehaviour

resetStates

public void resetStates(java.lang.String[] states)
Reset the children behaviours registered in the states indicated in the states parameter.

Parameters:
states - the names of the states that have to be reset


JADE