ptolemy.domains.fsm.kernel
Class Transition

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.Relation
          ptolemy.kernel.ComponentRelation
              ptolemy.domains.fsm.kernel.Transition

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

InterfaceAutomatonTransition, TDLTransition

public class Transition
extends ComponentRelation

A Transition has a source state and a destination state. A transition has a guard expression, which is evaluated to a boolean value. Whenever a transition is enabled, it must be taken immediately. That is, unlike some state machines formalisms, our guard is not just an enabler for the transition but rather a trigger for the transition.

A transition can contain actions. The way to specify actions is to give value to the outputActions parameter and the setActions parameter. The value of these parameters is a string of the form:

 command; command; ...
 

where each command has the form:

 destination = expression
 

For the outputActions parameter, destination is either

 portName
 

or

 portName(channelNumber)
 

Here, portName is the name of a port of the FSM actor, If no channelNumber is given, then the value is broadcasted to all channels of the port.

For the setActions parameter, destination is

 variableName
 

variableName identifies either a variable or parameter of the FSM actor, or a variable or parameter of the refinement of the destination state of the transition. To give a variable of the refinement, use a dotted name, as follows:

 refinementName.variableName
 

The expression is a string giving an expression in the usual Ptolemy II expression language. The expression may include references to variables and parameters contained by the FSM actor.

The outputActions and setActions parameters are not the only ways to specify actions. In fact, you can add action attributes that are instances of anything that inherits from Action. (Use the Add button in the Edit Parameters dialog).

An action is either a ChoiceAction or a CommitAction. The setActions parameter is a CommitAction, whereas the outputActions parameter is a ChoiceAction. A commit action is executed when the transition is taken to change the state of the FSM, in the postfire() method of FSMActor. A choice action, by contrast, is executed in the fire() method of the FSMActor when the transition is chosen, but not yet taken. The difference is subtle, and for most domains, irrelevant. A few domains, however, such as CT, which have fixed point semantics, where the fire() method may be invoked several times before the transition is taken (committed). For such domains, it is useful to have actions that fulfill the ChoiceAction interface. Such actions participate in the search for a fixed point, but do not change the state of the FSM.

A transition can be preemptive or non-preemptive. When a preemptive transition is chosen, the refinement of its source state is not fired. A non-preemptive transition is only chosen after the refinement of its source state is fired.

The reset parameter specifies whether the refinement of the destination state is reset when the transition is taken. There is no reset() method in the Actor interface, so the initialize() method of the refinement is called. Please note that this feature is still under development.

The nondeterministic parameter specifies whether this transition is nondeterministic. Here nondeterministic means that this transition may not be the only enabled transition at a time. The default value is a boolean token with value as false, meaning that if this transition is enabled, it must be the only enabled transition.

The defaultTransition parameter, if given a value true, specifies that this transition is enabled if and only if no other non-default transition is enabled.

Since:

Ptolemy II 0.4

Version:

$Id: Transition.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Xiaojun Liu, Edward A. Lee, Haiyang Zheng

See Also:

State, Action, ChoiceAction, CommitAction, CommitActionsAttribute, FSMActor, OutputActionsAttribute, Serialized Form

Accepted Rating:

Red (hyzheng)

Proposed Rating:

Yellow (hyzheng)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

private long	_actionListsVersion
private java.util.List	_choiceActionList
private java.util.List	_commitActionList
private State	_destinationState
private ASTPtRootNode	_guardParseTree
private long	_guardParseTreeVersion
private boolean	_nondeterministic
private ParseTreeEvaluator	_parseTreeEvaluator
private long	_parseTreeEvaluatorVersion
private TypedActor[]	_refinement
private long	_refinementVersion
private State	_sourceState
private long	_stateVersion
StringParameter	annotation An annotation that describes the transition.
Parameter	defaultTransition Indicator that this transition is a default transition.
Parameter	exitAngle Attribute the exit angle of a visual rendition.
Parameter	gamma Attribute giving the orientation of a self-loop.
StringAttribute	guardExpression Attribute specifying the guard expression.
Parameter	nondeterministic Parameter specifying whether this transition is nondeterministic.
OutputActionsAttribute	outputActions The action commands that produce outputs when the transition is taken.
Parameter	preemptive Parameter specifying whether this transition is preemptive.
StringAttribute	refinementName Attribute specifying one or more names of refinements.
Parameter	reset Parameter specifying whether the refinement of the destination state is reset when the transition is taken.
CommitActionsAttribute	setActions The action commands that set parameters when the transition is taken.

Fields inherited from class ptolemy.kernel.Relation

_linkList

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Constructor Summary

Transition(FSMActor container, java.lang.String name)
Construct a transition with the given name contained by the specified entity.

Transition(Workspace workspace)
Construct a transition in the given workspace with an empty string as a name.

Method Summary

private void	_checkConnectedStates()
protected void	_checkPort(Port port) Throw an IllegalActionException if the port cannot be linked to this transition.
private FSMDirector	_getDirector() Return the FSMDirector in charge of this transition, or null if there is none.
private void	_init()
private void	_updateActionLists()
void	attributeChanged(Attribute attribute) React to a change in an attribute.
java.util.List	choiceActionList() Return the list of choice actions contained by this transition.
java.lang.Object	clone(Workspace workspace) Clone the transition into the specified workspace.
java.util.List	commitActionList() Return the list of commit actions contained by this transition.
State	destinationState() Return the destination state of this transition.
java.lang.String	getGuardExpression() Return the guard expression.
java.lang.String	getLabel() Return a string describing this transition.
ParseTreeEvaluator	getParseTreeEvaluator() Return the parse tree evaluator used by this transition to evaluate the guard expression.
TypedActor[]	getRefinement() Return the refinements of this transition.
boolean	isDefault() Return true if this transition is a default transition.
boolean	isEnabled() Return true if the transition is enabled, that is the guard is true, or some event has been detected due to crossing some level.
boolean	isEnabled(ParserScope scope) Return true if the transition is enabled, that is the guard is true, or some event has been detected due to crossing some level.
boolean	isNondeterministic() Return true if this transition is nondeterministic.
boolean	isPreemptive() Return true if this transition is preemptive.
void	setContainer(CompositeEntity container) Override the base class to ensure that the proposed container is an instance of FSMActor or null; if it is null, then remove it from the container, and also remove any refinement(s) that it references that are not referenced by some other transition or state.
void	setGuardExpression(java.lang.String expression) Set the guard expression.
State	sourceState() Return the source state of this transition.

Methods inherited from class ptolemy.kernel.ComponentRelation

_checkContainer, _checkRelation, _propagateExistence, deepLinkedPortList, deepLinkedPorts, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, unlinkAll

Methods inherited from class ptolemy.kernel.Relation

_description, _getContainedObject, link, linkedObjectsList, linkedPortList, linkedPortList, linkedPorts, linkedPorts, numLinks, relationGroupList, unlink

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

annotation

public StringParameter annotation

An annotation that describes the transition. If this is non-empty, then a visual editor will be expected to put this annotation on or near the transition to document its function. This is a string that defaults to the empty string. Note that it can reference variables in scope using the notation $name.

defaultTransition

public Parameter defaultTransition

Indicator that this transition is a default transition. A default transition is enabled only if no other non-default transition is enabled. This is a boolean with default value false. If the value is true, then the guard expression is ignored.

exitAngle

public Parameter exitAngle

Attribute the exit angle of a visual rendition. This parameter contains a DoubleToken, initially with value PI/5. It must lie between -PI and PI. Otherwise, it will be truncated to lie within this range.

gamma

public Parameter gamma

Attribute giving the orientation of a self-loop. This is equal to the tangent at the midpoint (more or less). This parameter contains a DoubleToken, initially with value 0.0.

guardExpression

public StringAttribute guardExpression

Attribute specifying the guard expression.

nondeterministic

public Parameter nondeterministic

Parameter specifying whether this transition is nondeterministic. Here nondeterministic means that this transition may not be the only enabled transition at a time. The default value is a boolean token with value as false, meaning that if this transition is enabled, it must be the only enabled transition.

outputActions

public OutputActionsAttribute outputActions

The action commands that produce outputs when the transition is taken.

preemptive

public Parameter preemptive

Parameter specifying whether this transition is preemptive.

refinementName

public StringAttribute refinementName

Attribute specifying one or more names of refinements. The refinements must be instances of TypedActor and have the same container as the FSMActor containing this state, otherwise an exception will be thrown when getRefinement() is called. Usually, the refinement is a single name. However, if a comma-separated list of names is provided, then all the specified refinements will be executed. This attribute has a null expression or a null string as expression when the state is not refined.

reset

public Parameter reset

Parameter specifying whether the refinement of the destination state is reset when the transition is taken.

setActions

public CommitActionsAttribute setActions

The action commands that set parameters when the transition is taken.

_actionListsVersion

private long _actionListsVersion

_choiceActionList

private java.util.List _choiceActionList

_commitActionList

private java.util.List _commitActionList

_destinationState

private State _destinationState

_guardParseTree

private ASTPtRootNode _guardParseTree

_guardParseTreeVersion

private long _guardParseTreeVersion

_nondeterministic

private boolean _nondeterministic

_parseTreeEvaluator

private ParseTreeEvaluator _parseTreeEvaluator

_parseTreeEvaluatorVersion

private long _parseTreeEvaluatorVersion

_refinement

private TypedActor[] _refinement

_refinementVersion

private long _refinementVersion

_sourceState

private State _sourceState

_stateVersion

private long _stateVersion

Constructor Detail

Transition

public Transition(FSMActor container,
                  java.lang.String name)
           throws IllegalActionException,
                  NameDuplicationException

Construct a transition with the given name contained by the specified entity. The container argument must not be null, or a NullPointerException will be thrown. This transition will use the workspace of the container for synchronization and version counts. If the name argument is null, then the name is set to the empty string.

Parameters:

container - The container.

name - The name of the transition.

Throws:

IllegalActionException - If the container is incompatible with this transition.

NameDuplicationException - If the name coincides with any relation already in the container.

Transition

public Transition(Workspace workspace)
           throws IllegalActionException,
                  NameDuplicationException

Construct a transition in the given workspace with an empty string as a name. If the workspace argument is null, use the default workspace. The object is added to the workspace directory. Increment the version of the workspace.

Parameters:

workspace - The workspace for synchronization and version tracking.

Throws:

IllegalActionException - If the container is incompatible with this transition.

NameDuplicationException - If the name coincides with any relation already in the container.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

React to a change in an attribute. If the changed attribute is the preemptive parameter, evaluate the parameter. If the parameter is given an expression that does not evaluate to a boolean value, throw an exception; otherwise increment the version number of the workspace.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If thrown by the superclass attributeChanged() method, or the changed attribute is the preemptive parameter and is given an expression that does not evaluate to a boolean value.

choiceActionList

public java.util.List choiceActionList()

Return the list of choice actions contained by this transition.

Returns:

The list of choice actions contained by this transition.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the transition into the specified workspace. This calls the base class and then sets the attribute public members to refer to the attributes of the new transition.

Overrides:

clone in class ComponentRelation

Parameters:

workspace - The workspace for the new transition.

Returns:

A new transition.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

commitActionList

public java.util.List commitActionList()

Return the list of commit actions contained by this transition.

Returns:

The list of commit actions contained by this transition.

destinationState

public State destinationState()

Return the destination state of this transition.

Returns:

The destination state of this transition.

getGuardExpression

public java.lang.String getGuardExpression()

Return the guard expression. The guard expression should evaluate to a boolean value.

Returns:

The guard expression.

See Also:

setGuardExpression(java.lang.String)

getLabel

public java.lang.String getLabel()

Return a string describing this transition. The string has up to three lines. The first line is the guard expression, preceded by "guard: ". The second line is the outputActions preceded by the string "output: ". The third line is the setActions preceded by the string "set: ". If any of these is missing, then the corresponding line is omitted.

Returns:

A string describing this transition.

getParseTreeEvaluator

public ParseTreeEvaluator getParseTreeEvaluator()

Return the parse tree evaluator used by this transition to evaluate the guard expression.

Returns:

ParseTreeEvaluator for evaluating the guard expression.

getRefinement

public TypedActor[] getRefinement()
                           throws IllegalActionException

Return the refinements of this transition. The names of the refinements are specified by the refinementName attribute. The refinements must be instances of TypedActor and have the same container as the FSMActor containing this state, otherwise an exception is thrown. This method can also return null if there is no refinement. This method is read-synchronized on the workspace.

Returns:

The refinements of this state, or null if there are none.

Throws:

IllegalActionException - If the specified refinement cannot be found, or if a comma-separated list is malformed.

isDefault

public boolean isDefault()
                  throws IllegalActionException

Return true if this transition is a default transition. Return false otherwise.

Returns:

True if this transition is a default transition.

Throws:

IllegalActionException - If the defaultTransition parameter cannot be evaluated.

isEnabled

public boolean isEnabled()
                  throws IllegalActionException

Return true if the transition is enabled, that is the guard is true, or some event has been detected due to crossing some level.

Returns:

True if the transition is enabled and some event is detected.

Throws:

IllegalActionException - If thrown when evaluating the guard.

isEnabled

public boolean isEnabled(ParserScope scope)
                  throws IllegalActionException

Return true if the transition is enabled, that is the guard is true, or some event has been detected due to crossing some level.

Parameters:

scope - The parser scope in which the guard is to be evaluated.

Returns:

True If the transition is enabled and some event is detected.

Throws:

IllegalActionException - If thrown when evaluating the guard.

isNondeterministic

public boolean isNondeterministic()

Return true if this transition is nondeterministic. Return false otherwise.

Returns:

True if this transition is nondeterministic.

isPreemptive

public boolean isPreemptive()

Return true if this transition is preemptive. Whether this transition is preemptive is specified by the preemptive parameter.

Returns:

True if this transition is preemptive.

setContainer

public void setContainer(CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException

Override the base class to ensure that the proposed container is an instance of FSMActor or null; if it is null, then remove it from the container, and also remove any refinement(s) that it references that are not referenced by some other transition or state.

Overrides:

setContainer in class ComponentRelation

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If the transition would result in a recursive containment structure, or if this transition and container are not in the same workspace, or if the argument is not a FSMActor or null.

NameDuplicationException - If the container already has an relation with the name of this transition.

See Also:

ComponentRelation.getContainer()

setGuardExpression

public void setGuardExpression(java.lang.String expression)

Set the guard expression. The guard expression should evaluate to a boolean value.

Parameters:

expression - The guard expression.

See Also:

getGuardExpression()

sourceState

public State sourceState()

Return the source state of this transition.

Returns:

The source state of this transition.

_checkPort

protected void _checkPort(Port port)
                   throws IllegalActionException

Throw an IllegalActionException if the port cannot be linked to this transition. A transition has a source state and a destination state. A transition is only linked to the outgoing port of its source state and the incoming port of its destination state.

Overrides:

_checkPort in class ComponentRelation

Parameters:

port - The port to link to.

Throws:

IllegalActionException - If the port cannot be linked to this transition.

_checkConnectedStates

private void _checkConnectedStates()

_getDirector

private FSMDirector _getDirector()

Return the FSMDirector in charge of this transition, or null if there is none.

Returns:

The director in charge of this transition.

_init

private void _init()
            throws IllegalActionException,
                   NameDuplicationException

Throws:

IllegalActionException

NameDuplicationException

_updateActionLists

private void _updateActionLists()