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

Direct Known Subclasses:

AchieveREInitiator, AchieveREResponder, ContractNetInitiator, HandlerSelector, ProposeInitiator, ProposeResponder, SSContractNetResponder, SSIteratedAchieveREResponder, SubscriptionInitiator, SubscriptionResponder, TwoPh0Initiator, TwoPh1Initiator, TwoPh2Initiator, TwoPhInitiator, TwoPhResponder

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:

• register a single Behaviour as the initial state of the FSM by calling the method registerFirstState;
• register one or more Behaviours as the final states of the FSM by calling the method registerLastState;
• register one or more Behaviours as the intermediate states of the FSM by calling the method registerState;
• for each state of the FSM, register the transitions to the other states by calling the method registerTransition;
• the method registerDefaultTransition is also useful in order to register a default transition from a state to another state independently on the termination event of the source state.

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: 2008-04-15 11:09:57 +0200 (mar, 15 apr 2008) $ $Revision: 6029 $

Author:

Giovanni Caire - CSELT

See Also:

SequentialBehaviour, ParallelBehaviour, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	currentName
protected List	lastStates

Fields inherited from class jade.core.behaviours.Behaviour

myAgent

Constructor Summary

Constructors

Constructor and Description
FSMBehaviour() Default constructor, does not set the owner agent.
FSMBehaviour(Agent a) This constructor sets the owner agent.

Method Summary

Modifier and Type	Method and Description
protected boolean	checkTermination(boolean currentDone, int currentResult) Check whether this FSMBehaviour must terminate.
void	deregisterDefaultTransition(java.lang.String source) Deregister the default transition from a given source state.
Behaviour	deregisterState(java.lang.String name) Deregister a state of this FSMBehaviour.
void	deregisterTransition(java.lang.String source, int event) Deregister the transition from a given source state and identfied by a given termination event.
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)
boolean	hasDefaultTransition(java.lang.String source) Check if a default transition exits from a given source 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.
java.lang.String	stringifyTransitionTable()

Methods inherited from class jade.core.behaviours.CompositeBehaviour

action, done, resetChildren, setAgent

Methods inherited from class jade.core.behaviours.Behaviour

block, block, getAgent, getBehaviourName, getDataStore, getParent, isRunnable, onStart, restart, 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

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.

deregisterTransition

public void deregisterTransition(java.lang.String source,
                                 int event)

Deregister the transition from a given source state and identfied by a given termination event.

Parameters:

source - The name of the source state

event - The termination event that identifies the transition to be removed

deregisterDefaultTransition

public void deregisterDefaultTransition(java.lang.String source)

Deregister the default transition from a given source state.

Parameters:

source - The name of the source state

hasDefaultTransition

public boolean hasDefaultTransition(java.lang.String source)

Check if a default transition exits from a given source state.

Parameters:

source - The name of the source state

Returns:

true if a default transition exits from the given source state. false otherwise.

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

stringifyTransitionTable

public java.lang.String stringifyTransitionTable()