jade.core.behaviours
Class DistilledStateChartBehaviour

java.lang.Object
  extended by jade.core.behaviours.Behaviour
      extended by jade.core.behaviours.CompositeBehaviour
          extended by jade.core.behaviours.DistilledStateChartBehaviour
All Implemented Interfaces:
java.io.Serializable

public class DistilledStateChartBehaviour
extends jade.core.behaviours.CompositeBehaviour

DistilledStateChartBehaviour: a DSC using behaviours as states.

It is a CompositeBehaviour that executes its children behaviours according to a DSC defined by the user. More specifically each child represents a state in the DSC. The class provides methods to add 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 DistilledStateChartBehaviour:

A number of other methods are available in this class for generic tasks.

Author:
G. Fortino, F. Rango
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class jade.core.behaviours.Behaviour
jade.core.behaviours.Behaviour.RunnableChangedEvent
 
Field Summary
 
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
DistilledStateChartBehaviour()
          Default constructor, does not set the owner agent.
DistilledStateChartBehaviour(jade.core.Agent anAgent)
          This constructor sets the owner agent.
DistilledStateChartBehaviour(jade.core.Agent anAgent, java.lang.String aName)
          This constructor sets the owner agent and name of the behaviour (state).
DistilledStateChartBehaviour(jade.core.Agent anAgent, java.lang.String aName, boolean aPutback)
          This constructor sets the owner agent, name and sets the putback mode.
DistilledStateChartBehaviour(jade.core.Agent anAgent, java.lang.String aName, jade.lang.acl.MessageTemplate aTemplate)
          This constructor sets the owner agent, name and MessageTemplate.
DistilledStateChartBehaviour(jade.core.Agent anAgent, java.lang.String aName, jade.lang.acl.MessageTemplate aTemplate, boolean aPutback)
          This constructor sets the owner agent, name, MessageTemplate and the putback mode.
 
Method Summary
 void addFinalState(jade.core.behaviours.Behaviour state)
          Add a Behaviour as a final state of this DistilledStateChartBehaviour.
 void addInitialState(jade.core.behaviours.Behaviour state)
          Add a Behaviour as the initial state of this DistilledStateChartBehaviour.
 void addInitialState(int history)
          Add a history state as the initial state of this DistilledStateChartBehaviour.
 void addState(jade.core.behaviours.Behaviour state)
          Add a Behaviour as a state of this DistilledStateChartBehaviour.
 void addTransition(DistilledStateChartTransition trans)
          Adds the argument transition to the list of transitions in the root DistilledStateChartBehaviour.
 void addTransition(DistilledStateChartTransition trans, jade.core.behaviours.Behaviour source)
          Adds the argument transition to the list of transitions in the root DistilledStateChartBehaviour.
protected  boolean checkTermination(boolean currentDone, int currentResult)
          Check whether this DistilledStateChartBehaviour must terminate.
 boolean containsState(jade.core.behaviours.Behaviour b)
          Determines if the given state is already associated with this state.
 boolean containsTransition(DistilledStateChartTransition aTransition, jade.core.behaviours.Behaviour source)
          Determines if the given transition is already added.
static DistilledStateChartBehaviour createRootForDSCTemplate(DistilledStateChartBehaviour dsc)
          This method creates the root DistilledStateChartBehaviour using the DistilledStateChartBehaviour passed as parameter, in agreement to the DSC template with initial deep history state.
 void defaultDeepHistoryEntranceAction()
          This method is normally overridden and indicates the action related to the Default Deep History Entrance of the DSC.
 void defaultShallowHistoryEntranceAction()
          This method is normally overridden and indicates the action related to the Default Shallow History Entrance of the DSC.
 jade.util.leap.Collection getChildren()
          Return a Collection view of the children behaviours of this DistilledStateChartBehaviour.
protected  jade.core.behaviours.Behaviour getCurrent()
          Get the current child.
 jade.core.behaviours.Behaviour getDefaultDeepHistoryEntrance()
          Get Default Deep History Entrance of this DistilledStateChartBehaviour.
 jade.core.behaviours.Behaviour getDefaultShallowHistoryEntrance()
          Get Default Shallow History Entrance of this DistilledStateChartBehaviour.
 jade.core.behaviours.Behaviour getFinalState(int index)
          Returns the final state at the given index.
 int getFinalStateCount()
          Returns the number of final states associated with this DistilledStateChartBehaviour.
 jade.util.leap.Iterator getFinalStates()
          Returns the final states assocated with this DistilledStateChartBehaviour.
 java.lang.Object getInitialState()
          Returns the initial state of this DistilledStateChartBehaviour (the initial state returned is a Behaviour or an Integer that represents an history state of type DistilledStateChartTransition.SHALLOW_HISTORY or DistilledStateChartTransition.DEEP_HISTORY).
 int getLastExitValue()
          Get the exit value of the last executed state.
 jade.lang.acl.MessageTemplate getMainTemplate()
          Get the MessageTemplate.
 jade.core.behaviours.CompositeBehaviour getParent()
          Returns the parent behaviour of this behaviour.
 boolean getPutback()
          Get the putback mode.
 int getStateCount()
          Returns the number of states contained within this state.
 jade.util.leap.Collection getStatesWithTransitions()
          Returns the collection of only the transitions that I know about (this method has to work in this way!
 DistilledStateChartTransition getTransition(int index, jade.core.behaviours.Behaviour source)
          Returns the transition at the given index.
 int getTransitionCount(jade.core.behaviours.Behaviour source)
          Returns the number of transitions with the given source state.
 jade.util.leap.Iterator getTransitions(jade.core.behaviours.Behaviour source)
          Return an Iterator of the transitions with the given source state.
 jade.core.behaviours.Behaviour getTransitionSource(DistilledStateChartTransition t)
          Returns the source behaviour of the given transition.
 jade.core.behaviours.Behaviour getWrappedState(jade.core.behaviours.Behaviour aState)
          Helper to extract the wrapped state of the argument.
protected  void handle(jade.core.behaviours.Behaviour.RunnableChangedEvent rce)
          Handle block/restart notifications.
 void initialAction()
          This method is normally overridden and indicates the action related to the initial state of the DSC to execute when we enter the DSC and we have to leave again from the initial state (it represents the existing action on the transition that connects the black circle to the initial state in the DSC).
 int onEnd()
          "onEnd" method for this DSC.
 void onStart()
          "onStart" method for this DSC.
 void removeAllTransitions()
          Remove all the transitions.
 void removeInitialStateHistory()
          Delete the initial history state (H or H*) from this DSC.
 void removeState(jade.core.behaviours.Behaviour state)
          Delete the argument state from this DSC.
 void removeTransition(DistilledStateChartTransition aTransition)
          Remove the argument transition from the set of known transitions by calling the specific removeTransition on this behaviour.
 void removeTransition(DistilledStateChartTransition aTransition, jade.core.behaviours.Behaviour source)
          Remove the argument transition from the set of known transitions.
 void reset()
          Reset this DistilledStateChartBehaviour.
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.
 void setAgent(jade.core.Agent a)
          Overridden from the base class to make sure that the Wrapper objects have their agent pointers set as well.
protected  void setCurrent(jade.core.behaviours.Behaviour state)
          Establish who is the current state.
 void setDefaultDeepHistoryEntrance(jade.core.behaviours.Behaviour state)
          Set Default Deep History Entrance of this DistilledStateChartBehaviour.
 void setDefaultShallowHistoryEntrance(jade.core.behaviours.Behaviour state)
          Set Default Shallow History Entrance of this DistilledStateChartBehaviour.
 void setMainTemplate(jade.lang.acl.MessageTemplate aTemplate)
          To set the MessageTemplate.
 void setPutback(boolean aPutback)
          To set the putback mode.
 
Methods inherited from class jade.core.behaviours.CompositeBehaviour
action, done, handleBlockEvent, handleRestartEvent, registerAsChild, resetChildren
 
Methods inherited from class jade.core.behaviours.Behaviour
actionWrapper, block, block, getBehaviourName, getDataStore, getExecutionState, getRestartCounter, isRunnable, restart, root, setBehaviourName, setDataStore, setExecutionState
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DistilledStateChartBehaviour

public DistilledStateChartBehaviour()
Default constructor, does not set the owner agent. The owner agent has got to be set before much else is done (setAgent can be called to do this).


DistilledStateChartBehaviour

public DistilledStateChartBehaviour(jade.core.Agent anAgent)
This constructor sets the owner agent.

Parameters:
anAgent - the agent this behaviour belongs to.

DistilledStateChartBehaviour

public DistilledStateChartBehaviour(jade.core.Agent anAgent,
                                    java.lang.String aName)
This constructor sets the owner agent and name of the behaviour (state).

Parameters:
anAgent - the agent this behaviour belongs to.
aName - the name of the behaviour.

DistilledStateChartBehaviour

public DistilledStateChartBehaviour(jade.core.Agent anAgent,
                                    java.lang.String aName,
                                    jade.lang.acl.MessageTemplate aTemplate)
This constructor sets the owner agent, name and MessageTemplate.

Parameters:
anAgent - the agent this behaviour belongs to.
aName - the name of the behaviour.
aTemplate - the main template

DistilledStateChartBehaviour

public DistilledStateChartBehaviour(jade.core.Agent anAgent,
                                    java.lang.String aName,
                                    boolean aPutback)
This constructor sets the owner agent, name and sets the putback mode.

Parameters:
anAgent - the agent this behaviour belongs to.
aName - the name of the behaviour.
aPutback - the putback mode

DistilledStateChartBehaviour

public DistilledStateChartBehaviour(jade.core.Agent anAgent,
                                    java.lang.String aName,
                                    jade.lang.acl.MessageTemplate aTemplate,
                                    boolean aPutback)
This constructor sets the owner agent, name, MessageTemplate and the putback mode.

Parameters:
anAgent - the agent this behaviour belongs to.
aName - the name of the behaviour.
aTemplate - the main template
aPutback - the putback mode
Method Detail

setPutback

public void setPutback(boolean aPutback)
To set the putback mode.

Parameters:
aPutback - boolean to set the putback mode

setMainTemplate

public void setMainTemplate(jade.lang.acl.MessageTemplate aTemplate)
To set the MessageTemplate. Null means not filtering.

Parameters:
aTemplate - the filtering MessageTemplate

getPutback

public boolean getPutback()
Get the putback mode.


getMainTemplate

public jade.lang.acl.MessageTemplate getMainTemplate()
Get the MessageTemplate.


getParent

public jade.core.behaviours.CompositeBehaviour getParent()
Returns the parent behaviour of this behaviour.

Overrides:
getParent in class jade.core.behaviours.Behaviour
Returns:
the parent behaviour of this behaviour.

addState

public void addState(jade.core.behaviours.Behaviour state)
Add a Behaviour as a state of this DistilledStateChartBehaviour. When the DSC reaches this state the added Behaviour will be executed. If the added state is a DistilledStateChartBehaviour, then we check to see if it has any transitions and take them out of the state and put them into our own DSC parent.

Parameters:
state - The Behaviour representing the state

containsState

public boolean containsState(jade.core.behaviours.Behaviour b)
Determines if the given state is already associated with this state.

Parameters:
b - Tests to see if this argument is a state inside of me.
Returns:
True if it is present, false otherwise.

getStateCount

public int getStateCount()
Returns the number of states contained within this state.

Returns:
The number of states within me.

addInitialState

public void addInitialState(jade.core.behaviours.Behaviour state)
Add a Behaviour as the initial state of this DistilledStateChartBehaviour.

Parameters:
state - The Behaviour representing the state

addInitialState

public void addInitialState(int history)
Add a history state as the initial state of this DistilledStateChartBehaviour.

Parameters:
history - The history type: DistilledStateChartTransition.SHALLOW_HISTORY or DistilledStateChartTransition.DEEP_HISTORY

getInitialState

public java.lang.Object getInitialState()
Returns the initial state of this DistilledStateChartBehaviour (the initial state returned is a Behaviour or an Integer that represents an history state of type DistilledStateChartTransition.SHALLOW_HISTORY or DistilledStateChartTransition.DEEP_HISTORY).

Returns:
the initial state of this DistilledStateChartBehaviour.

addFinalState

public void addFinalState(jade.core.behaviours.Behaviour state)
Add a Behaviour as a final state of this DistilledStateChartBehaviour. When the DSC reaches this state the added Behaviour will be executed and, when completed, the DistilledStateChartBehaviour will terminate too.

Parameters:
state - The Behaviour representing the state

getFinalStates

public jade.util.leap.Iterator getFinalStates()
Returns the final states assocated with this DistilledStateChartBehaviour.

Returns:
An iterator of all of the final states of this DSC.

getFinalStateCount

public int getFinalStateCount()
Returns the number of final states associated with this DistilledStateChartBehaviour.

Returns:
How many final states there are in this DSC.

getFinalState

public jade.core.behaviours.Behaviour getFinalState(int index)
Returns the final state at the given index.

Parameters:
index - The index of one of the final states in this DSC.
Returns:
Given an index, returns the specific final state.

removeState

public void removeState(jade.core.behaviours.Behaviour state)
Delete the argument state from this DSC. If the state is an initial state or a final state, we remove it too. Note - we currently do not delete any transitions associated with this state. We could and probably should at least delete those that are sourced by this state. But then again, it is up to the user to take care of this.

Parameters:
state - the behaviour to delete.
Throws:
java.lang.RuntimeException - if the state that we attempt to remove is not defined in the DSC.

removeInitialStateHistory

public void removeInitialStateHistory()
Delete the initial history state (H or H*) from this DSC.


addTransition

public void addTransition(DistilledStateChartTransition trans)
Adds the argument transition to the list of transitions in the root DistilledStateChartBehaviour. Calls "addTransition" with the "this" as the state argument.

Parameters:
trans - the transition that we are adding.

addTransition

public void addTransition(DistilledStateChartTransition trans,
                          jade.core.behaviours.Behaviour source)
Adds the argument transition to the list of transitions in the root DistilledStateChartBehaviour.

Parameters:
trans - the transition that we are adding
source - the source of the transition

containsTransition

public boolean containsTransition(DistilledStateChartTransition aTransition,
                                  jade.core.behaviours.Behaviour source)
Determines if the given transition is already added.

Parameters:
aTransition - Tests to see if this argument is a transition already added.
source - source of the transition.
Returns:
True if it is present, false otherwise.

removeTransition

public void removeTransition(DistilledStateChartTransition aTransition)
Remove the argument transition from the set of known transitions by calling the specific removeTransition on this behaviour.

Parameters:
aTransition - the transition to remove.
Throws:
java.lang.RuntimeException - is thrown if the argument transition isn't in the set of transitions.

removeTransition

public void removeTransition(DistilledStateChartTransition aTransition,
                             jade.core.behaviours.Behaviour source)
Remove the argument transition from the set of known transitions.

Parameters:
aTransition - the transition to remove.
source - The source state that may have the transition.
Throws:
java.lang.RuntimeException - is thrown if the argument transition isn't in the set of transitions.

removeAllTransitions

public void removeAllTransitions()
Remove all the transitions.


getLastExitValue

public int getLastExitValue()
Get the exit value of the last executed state.

Returns:
the exit value of the last executed state.

scheduleFirst

protected void scheduleFirst()
Prepare the first child for execution.

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

scheduleNext

protected void scheduleNext(boolean currentDone,
                            int currentResult)
This method schedules the next child to be executed. Basically this code does nothing. That is because the new current is already set in the transition processing code.

Specified by:
scheduleNext in class jade.core.behaviours.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)

initialAction

public void initialAction()
This method is normally overridden and indicates the action related to the initial state of the DSC to execute when we enter the DSC and we have to leave again from the initial state (it represents the existing action on the transition that connects the black circle to the initial state in the DSC). If this action isn't defined, it isn't executed.


defaultShallowHistoryEntranceAction

public void defaultShallowHistoryEntranceAction()
This method is normally overridden and indicates the action related to the Default Shallow History Entrance of the DSC. If this action isn't defined, it isn't executed.


defaultDeepHistoryEntranceAction

public void defaultDeepHistoryEntranceAction()
This method is normally overridden and indicates the action related to the Default Deep History Entrance of the DSC. If this action isn't defined, it isn't executed.


createRootForDSCTemplate

public static DistilledStateChartBehaviour createRootForDSCTemplate(DistilledStateChartBehaviour dsc)
This method creates the root DistilledStateChartBehaviour using the DistilledStateChartBehaviour passed as parameter, in agreement to the DSC template with initial deep history state.


checkTermination

protected boolean checkTermination(boolean currentDone,
                                   int currentResult)
Check whether this DistilledStateChartBehaviour must terminate. Note: this happens only when the last child is done and it is a final state.

Specified by:
checkTermination in class jade.core.behaviours.CompositeBehaviour
Parameters:
currentDone - tells if the behaviour that just ran set its done flag to true.
currentResult - is the result that the behaviour that just ran returned.
Returns:
true when the last child has terminated and it represents a final state, false otherwise.
See Also:
CompositeBehaviour.checkTermination(boolean, int)

getWrappedState

public jade.core.behaviours.Behaviour getWrappedState(jade.core.behaviours.Behaviour aState)
Helper to extract the wrapped state of the argument.

Parameters:
aState - the state that we are looking up.
Returns:
Either the wrapped state or null if it isn't wrapped yet.

getCurrent

protected jade.core.behaviours.Behaviour getCurrent()
Get the current child.

Specified by:
getCurrent in class jade.core.behaviours.CompositeBehaviour
Returns:
The behaviour that is current.
See Also:
CompositeBehaviour.getCurrent()

setCurrent

protected void setCurrent(jade.core.behaviours.Behaviour state)
Establish who is the current state.

Parameters:
state - The state to set the current to.

getDefaultShallowHistoryEntrance

public jade.core.behaviours.Behaviour getDefaultShallowHistoryEntrance()
Get Default Shallow History Entrance of this DistilledStateChartBehaviour.

Returns:
Behaviour that represents Default Shallow History Entrance.

setDefaultShallowHistoryEntrance

public void setDefaultShallowHistoryEntrance(jade.core.behaviours.Behaviour state)
Set Default Shallow History Entrance of this DistilledStateChartBehaviour.

Parameters:
state - Behaviour that represents Default Shallow History Entrance.

getDefaultDeepHistoryEntrance

public jade.core.behaviours.Behaviour getDefaultDeepHistoryEntrance()
Get Default Deep History Entrance of this DistilledStateChartBehaviour.

Returns:
Behaviour that represents Default Deep History Entrance.

setDefaultDeepHistoryEntrance

public void setDefaultDeepHistoryEntrance(jade.core.behaviours.Behaviour state)
Set Default Deep History Entrance of this DistilledStateChartBehaviour.

Parameters:
state - Behaviour that represents Default Deep History Entrance.

getChildren

public jade.util.leap.Collection getChildren()
Return a Collection view of the children behaviours of this DistilledStateChartBehaviour.

Specified by:
getChildren in class jade.core.behaviours.CompositeBehaviour
Returns:
The collection.
See Also:
CompositeBehaviour.getChildren()

getTransitions

public jade.util.leap.Iterator getTransitions(jade.core.behaviours.Behaviour source)
Return an Iterator of the transitions with the given source state.

Parameters:
source - The source state of the transitions.
Returns:
The Iterator.

getTransitionSource

public jade.core.behaviours.Behaviour getTransitionSource(DistilledStateChartTransition t)
Returns the source behaviour of the given transition.


getTransitionCount

public int getTransitionCount(jade.core.behaviours.Behaviour source)
Returns the number of transitions with the given source state.

Parameters:
source - The source state of the transitions.
Returns:
The number of transitions.

getTransition

public DistilledStateChartTransition getTransition(int index,
                                                   jade.core.behaviours.Behaviour source)
Returns the transition at the given index.

Parameters:
index - The index of the transition that we are looking up.
source - The source state of the transition.
Returns:
The transition.

getStatesWithTransitions

public jade.util.leap.Collection getStatesWithTransitions()
Returns the collection of only the transitions that I know about (this method has to work in this way! don't modify!).

Returns:
The collection of transitions.

reset

public void reset()
Reset this DistilledStateChartBehaviour.

Overrides:
reset in class jade.core.behaviours.CompositeBehaviour

setAgent

public void setAgent(jade.core.Agent a)
Overridden from the base class to make sure that the Wrapper objects have their agent pointers set as well.

Overrides:
setAgent in class jade.core.behaviours.CompositeBehaviour
Parameters:
a - The agent that you are setting for this behaviour.

handle

protected void handle(jade.core.behaviours.Behaviour.RunnableChangedEvent rce)
Handle block/restart notifications. A DistilledStateChartBehaviour 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 jade.core.behaviours.Behaviour
Parameters:
rce - The event to handle.

onEnd

public int onEnd()
"onEnd" method for this DSC. "onStart" and "onEnd" represent the entry/exit codes defined in the UML state machine model. They are called in a hierarchical fashion as per that model.

Overrides:
onEnd in class jade.core.behaviours.Behaviour
Returns:
the last exit value.

onStart

public void onStart()
"onStart" method for this DSC. "onStart" and "onEnd" represent the entry/exit codes defined in the UML state machine model. They are called in a hierarchical fashion as per that model.

Overrides:
onStart in class jade.core.behaviours.Behaviour