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: Transition.java 70402 2014-10-23 00:52:20Z cxh $

Author:

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

See Also:

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

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

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

All Methods Instance Methods Concrete Methods
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.

Class Transition

Nested Class Summary

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

Field Summary

Fields inherited from class ptolemy.kernel.Relation

Fields inherited from class ptolemy.kernel.util.NamedObj

Constructor Summary

Method Summary

Methods inherited from class ptolemy.kernel.ComponentRelation

Methods inherited from class ptolemy.kernel.Relation

Methods inherited from class ptolemy.kernel.util.NamedObj

Methods inherited from class java.lang.Object

Field Detail

annotation

defaultTransition

error

exitAngle

fsmTransitionParameterName

gamma

guardExpression

history

immediate

nondeterministic

outputActions

preemptive

refinementName

setActions

showFSMTransitionParameter

termination

Constructor Detail

Transition

Transition

Method Detail

attributeChanged

choiceActionList

clone

commitActionList

destinationState

getFullLabel

getGuardExpression

getLabel

getParseTreeEvaluator

getRefinement

isDefault

isEnabled

isEnabled

isErrorTransition

isHistory

isImmediate

isNondeterministic

isTermination

isPreemptive

setContainer

setGuardExpression

setFsmTransitionParameter

sourceState

_checkPort