jade.core.behaviours
Class FSMBehaviour

java.lang.Object
  |
  +--jade.core.behaviours.Behaviour
        |
        +--jade.core.behaviours.CompositeBehaviour
              |
              +--jade.core.behaviours.FSMBehaviour
Direct Known Subclasses:
AchieveREResponder, ContractNetResponder, jade.proto.Initiator, SubscriptionResponder

public class FSMBehaviour
extends CompositeBehaviour

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: 2003/03/04 14:04:54 $ $Revision: 1.17 $
Author:
Giovanni Caire - CSELT
See Also:
SequentialBehaviour, ParallelBehaviour, Serialized Form

Inner classes inherited from class jade.core.behaviours.Behaviour
Behaviour.RunnableChangedEvent
 
Fields inherited from class jade.core.behaviours.CompositeBehaviour
currentExecuted
 
Fields inherited from class jade.core.behaviours.Behaviour
myAgent, myEvent, NOTIFY_DOWN, NOTIFY_UP, parent, STATE_BLOCKED, STATE_READY, STATE_RUNNING
 
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.
protected  void forceTransitionTo(java.lang.String next)
           
 Collection getChildren()
          Return a Collection view of the children of this SequentialBehaviour
protected  Behaviour getCurrent()
          Get the current child
 int getLastExitValue()
           
 java.lang.String getName(Behaviour state)
           
 Behaviour getState(java.lang.String name)
           
protected  void handle(Behaviour.RunnableChangedEvent rce)
          Handle block/restart notifications.
 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, onStart, restart, setAgent
 
Methods inherited from class jade.core.behaviours.Behaviour
actionWrapper, block, getBehaviourName, getDataStore, isRunnable, root, setBehaviourName, setDataStore
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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.

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)
Returns:
the Behaviour representing the state whose name is name.

getName

public java.lang.String getName(Behaviour state)
Returns:
the name of the state represented by Behaviour state.

getLastExitValue

public int getLastExitValue()
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 CompositeBehaviour
Tags copied from class: CompositeBehaviour
See Also:
Behaviour.onEnd()

scheduleFirst

protected void scheduleFirst()
Prepare the first child for execution. The first child is the Behaviour registered as the first state of this FSMBehaviour
Overrides:
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.
Overrides:
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)

checkTermination

protected boolean checkTermination(boolean currentDone,
                                   int currentResult)
Check whether this FSMBehaviour must terminate.
Overrides:
checkTermination in class CompositeBehaviour
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
Overrides:
getCurrent in class CompositeBehaviour
See Also:
CompositeBehaviour.getCurrent()

getChildren

public Collection getChildren()
Return a Collection view of the children of this SequentialBehaviour
Overrides:
getChildren in class CompositeBehaviour
See Also:
CompositeBehaviour.getChildren()

forceTransitionTo

protected void forceTransitionTo(java.lang.String next)

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

handle

protected void handle(Behaviour.RunnableChangedEvent rce)
Handle block/restart notifications. An FSMBehaviour is blocked only when its currently active child is blocked, and becomes ready again when its current child is ready. This method takes care of the various possibilities.
Overrides:
handle in class Behaviour
Parameters:
rce - The event to handle.