ptolemy.domains.fsm.kernel
Class Transition

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.Relation
          extended byptolemy.kernel.ComponentRelation
              extended byptolemy.domains.fsm.kernel.Transition
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable
Direct Known Subclasses:
InterfaceAutomatonTransition

public class Transition
extends ComponentRelation

A Transition has a source state and a destination state. A transition has a guard expression and a trigger expression. Both expressions should evaluate to a boolean value. The trigger of a transition must be true whenever the guard is true. A transition is enabled and can be taken when its guard is true. A transition is triggered and must be taken when its trigger is true.

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 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.

Since:
Ptolemy II 0.4
Version:
$Id: Transition.java,v 1.73 2004/04/13 05:12:56 cxh Exp $
Author:
Xiaojun Liu and Edward A. Lee
See Also:
State, Action, ChoiceAction, CommitAction, CommitActionsAttribute, FSMActor, OutputActionsAttribute, Serialized Form
Accepted Rating:
Yellow (liuxj)
Proposed Rating:
Yellow (liuxj)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Field Summary
 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.
 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.
 StringAttribute triggerExpression
          Attribute specifying the trigger expression.
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _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
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 getGuardExpression()
          Return the guard expression.
 java.lang.String getLabel()
          Return a string describing this transition.
 TypedActor[] getRefinement()
          Return the refinements of this transition.
 RelationList getRelationList()
          Return the trigger expression.
 java.lang.String getTriggerExpression()
          Return the trigger expression.
 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 isPreemptive()
          Return true if this transition is preemptive.
 boolean isTriggered()
          Return true if the transition is triggered.
 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.
 void setTriggerExpression(java.lang.String expression)
          Set the trigger expression.
 State sourceState()
          Return the source state of this transition.
 
Methods inherited from class ptolemy.kernel.ComponentRelation
_checkContainer, _propagateExistence, deepLinkedPortList, deepLinkedPorts, getContainer, setName, unlinkAll
 
Methods inherited from class ptolemy.kernel.Relation
_description, _getContainedObject, _getPortList, linkedPortList, linkedPortList, linkedPorts, linkedPorts, numLinks
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, uniqueName, validateSettables, workspace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

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.


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.


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.


triggerExpression

public StringAttribute triggerExpression
Attribute specifying the trigger expression.


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.

Constructor Detail

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.

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.
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.

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.

getLabel

public java.lang.String getLabel()
Return a string describing this transition. The string has two lines. The first line is the guard expression. The second line is the concatenation of the expressions of outputActions and setActions.

Returns:
A string describing this transition.

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.

getRelationList

public RelationList getRelationList()
Return the trigger expression. The trigger expression should evaluate to a boolean value.

Returns:
The trigger expression.

getTriggerExpression

public java.lang.String getTriggerExpression()
Return the trigger expression. The trigger expression should evaluate to a boolean value.

Returns:
The trigger expression.

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.

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.

isTriggered

public boolean isTriggered()
                    throws IllegalActionException
Return true if the transition is triggered.

Returns:
True if the transition is triggered.
Throws:
IllegalActionException - If thrown when evaluating the trigger, or the trigger is true but the guard is false.

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.

setTriggerExpression

public void setTriggerExpression(java.lang.String expression)
Set the trigger expression. The trigger expression should evaluate to a boolean value.

Parameters:
expression - The trigger expression.

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.