ptolemy.domains.modal.kernel

Class Transition

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.Relation

ptolemy.kernel.ComponentRelation

ptolemy.domains.modal.kernel.Transition

All Implemented Interfaces:

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

Direct Known Subclasses:

InterfaceAutomatonTransition, SchedulingRelation, TDLTransition, TransitionMatcher

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 out of the current state is enabled, it must be taken in the current firing. 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 broadcast 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 history parameter specifies whether the refinement of the destination state refinement is initialized when the transition is taken. By default, this is false, which means that the destination refinement is initialized. If you change this to true, then the destination refinement will not be initialized, so when the state is re-entered, the refinement will continue executing where it left off.

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 immediateTransition parameter, if given a value true, specifies that this transition is may be taken as soon as its source state is entered, in the same iteration. This may lead to transient states, where a state is passed through without ever becoming the current state.

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

The error parameter, if given a value true, specifies that this transition is enabled if the refinement of the source state of the transition throws a model error or an exception while executing. The default value is a boolean token with value false. When such an exception or model error occurs, two variables are set that may be used in the guard or the output or set actions of this transition:

• errorMessage: The error message (a string).
• errorClass: The class of the exception thrown.

In addition, if the exception is an instance of KernelException or a subclass (such as IllegalActionException), then a third variable is set:

• errorCause: The Ptolemy object that caused the exception.

The errorCause is made available as an ObjectToken on which you can invoke methods such as getName() in the guard or output or set actions of this transition.

Since:

Ptolemy II 8.0

Version:

$Id$

Author:

Xiaojun Liu, Edward A. Lee, Haiyang Zheng, Christian Motika

See Also:

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

Pt.AcceptedRating:

Red (hyzheng)

Pt.ProposedRating:

Yellow (hyzheng)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
StringParameter	annotation An annotation that describes the transition.
Parameter	defaultTransition Indicator that this transition is a default transition.
Parameter	error Parameter specifying whether this transition should be treated as an error transition.
Parameter	exitAngle Attribute the exit angle of a visual rendition.
Parameter	fsmTransitionParameterName The name of the transition, which defaults to the name of the transition followed by the string "Parameter".
Parameter	gamma Attribute giving the orientation of a self-loop.
StringAttribute	guardExpression Attribute specifying the guard expression.
Parameter	history Parameter specifying whether the refinements of the destination state are initialized when the transition is taken.
Parameter	immediate Parameter specifying whether this transition is immediate.
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 Deprecated. Use immediate transitions.
CommitActionsAttribute	setActions The action commands that set parameters when the transition is taken.
Parameter	showFSMTransitionParameter True of the the value of the fsmTransitionParameterName parameter should be returned by getLabel().
Parameter	termination Parameter specifying whether the refinements of the origin state must have terminated (postfire has returned false) for the transition to be enabled.

Fields inherited from class ptolemy.kernel.Relation

_linkList

Fields inherited from class ptolemy.kernel.util.NamedObj

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

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
protected void	_checkPort(Port port) Throw an IllegalActionException if the port cannot be linked to this transition.
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	getFullLabel() Return the full label, which may include the guard expression, the output expression and the set actions.
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, and false if the guard evaluates to false.
boolean	isEnabled(ParserScope scope) Return true if the transition is enabled, that is the guard is true, and false if the guard evaluates to false.
boolean	isErrorTransition() Return true if this transition is an error transition.
boolean	isHistory() Return true if this transition is a history transition.
boolean	isImmediate() Return true if this transition is immediate.
boolean	isNondeterministic() Return true if this transition is nondeterministic.
boolean	isPreemptive() Return true if this transition is preemptive.
boolean	isTermination() Return true if this transition is a termination transition.
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	setFsmTransitionParameter(FSMTransitionParameter parameter) Set the FSMTransitionParameter.
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, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, 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, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, 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.

error

public Parameter error

Parameter specifying whether this transition should be treated as an error transition. The default value is a boolean with the value false, which indicates that this transition is not an error transition. If the value is true, that this transition is enabled if and only if the refinement of the source state of the transition throws a model error while executing.

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.

fsmTransitionParameterName

public Parameter fsmTransitionParameterName

The name of the transition, which defaults to the name of the transition followed by the string "Parameter".

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.

history

public Parameter history

Parameter specifying whether the refinements of the destination state are initialized when the transition is taken. This is a boolean that defaults to false.

immediate

public Parameter immediate

Parameter specifying whether this transition is immediate.

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

@Deprecated
public StringAttribute refinementName

Deprecated. Use immediate transitions.

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.

setActions

public CommitActionsAttribute setActions

The action commands that set parameters when the transition is taken. By default, this is empty.

showFSMTransitionParameter

public Parameter showFSMTransitionParameter

True of the the value of the fsmTransitionParameterName parameter should be returned by getLabel().

termination

public Parameter termination

Parameter specifying whether the refinements of the origin state must have terminated (postfire has returned false) for the transition to be enabled.

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.

getFullLabel

public java.lang.String getFullLabel()

Return the full label, which may include the guard expression, the output expression and the set actions.

Returns:

The full label

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 default parameter cannot be evaluated.

isEnabled

public boolean isEnabled()
                  throws IllegalActionException

Return true if the transition is enabled, that is the guard is true, and false if the guard evaluates to false.

Returns:

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

Throws:

IllegalActionException - If the guard cannot be evaluated.

isEnabled

public boolean isEnabled(ParserScope scope)
                  throws IllegalActionException

Return true if the transition is enabled, that is the guard is true, and false if the guard evaluates to false.

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 the guard cannot be evaluated.

isErrorTransition

public boolean isErrorTransition()
                          throws IllegalActionException

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

Returns:

True if this transition is an error transition.

Throws:

IllegalActionException - If the parameter cannot be evaluated.

isHistory

public boolean isHistory()
                  throws IllegalActionException

Return true if this transition is a history transition. If the history parameter has been set to true, then return true. Otherwise, check to see whether the model was created by a Ptolemy version earlier than 9.1.devel. If it was not, return false, the new default. If it was, then look for a parameter named "reset", and set the history parameter to the complement of it and return that value. If there is no such parameter, then we have to assume the default behavior that prevailed before 9.1.devel, and set history to true.

Returns:

true if this transition is a history transition.

Throws:

IllegalActionException - If the value of the history parameter cannot be read.

isImmediate

public boolean isImmediate()

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

Returns:

True if this transition is immediate.

isNondeterministic

public boolean isNondeterministic()

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

Returns:

True if this transition is nondeterministic.

isTermination

public boolean isTermination()
                      throws IllegalActionException

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

Returns:

True if this transition is a termination transition.

Throws:

IllegalActionException - If the parameter cannot be evaluated.

isPreemptive

public boolean isPreemptive()
                     throws IllegalActionException

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.

Throws:

IllegalActionException - If the parameter cannot be evaluated.

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()

setFsmTransitionParameter

public void setFsmTransitionParameter(FSMTransitionParameter parameter)

Set the FSMTransitionParameter.

Parameters:

parameter - The parameter.

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.