ptolemy.domains.modal.kernel
Class State

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.domains.modal.kernel.State

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, ConfigurableEntity, Changeable, Configurable, Debuggable, DebugListener, Derivable, DropTargetHandler, Flowable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

Event, FmvState, StateMatcher

public class State
extends ComponentEntity
implements ConfigurableEntity, DropTargetHandler, Flowable

A State has two ports: one for linking incoming transitions, the other for outgoing transitions. When the FSMActor containing a state is the mode controller of a modal model, the state can be refined by one or more instances of TypedActor. The refinements must have the same container as the FSMActor. During execution of a modal model, only the mode controller and the refinements of the current state of the mode controller react to input to the modal model and produce output. The outgoing transitions from a state are either preemptive or non-preemptive. When a modal model is fired, if a preemptive transition from the current state of the mode controller is chosen, the refinements of the current state are not fired. Otherwise the refinements are fired before choosing a non-preemptive transition.

Since:

Ptolemy II 8.0

Version:

$Id: State.java 57044 2010-01-27 22:41:05Z cxh $

Author:

Xiaojun Liu

See Also:

Transition, FSMActor, FSMDirector, Serialized Form

Accepted Rating:

Yellow (kienhuis)

Proposed Rating:

Yellow (liuxj)

Nested Class Summary

private static class	State.InvisibleModalModel An attribute that marks a modal model is created because the designer opens a design pattern whose top-level is an FSMActor.
private static class	State.UpdateContentsRequest A change request the updates the refinements of a state if it contains a configure element.

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

private Configurer	_configurer
private java.lang.String	_configureSource
private java.util.List	_nonpreemptiveTransitionList
private java.util.List	_preemptiveTransitionList
private TypedActor[]	_refinement
private long	_refinementVersion
private long	_transitionListVersion
ComponentPort	incomingPort The port linking incoming transitions.
Parameter	isFinalState An indicator of whether this state is a final state.
Parameter	isInitialState An indicator of whether this state is the initial state.
ComponentPort	outgoingPort The port linking outgoing transitions.
StringAttribute	refinementName Attribute specifying one or more names of refinements.
Parameter	saveRefinementsInConfigurer A boolean attribute to decide refinements of this state should be exported as configurations of this state or not.

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

State(CompositeEntity container, java.lang.String name)
Construct a state with the given name contained by the specified composite entity.

Method Summary

protected void	_exportMoMLContents(java.io.Writer output, int depth) Write a MoML description of the contents of this object, which in this class are the attributes plus the ports.
private void	_populateRefinements() Move the refinements in the configurer of this state to the closest modal model above this state in the model hierarchy.
private void	_updateTransitionLists() Update the cached transition lists.
void	attributeChanged(Attribute attribute) React to a change in an attribute.
java.lang.Object	clone(Workspace workspace) Clone the state into the specified workspace.
void	configure(java.net.URL base, java.lang.String source, java.lang.String text) Configure the object with data from the specified input source (a URL) and/or textual data.
void	dropObject(NamedObj target, java.util.List dropObjects, java.lang.String moml) React to a list of objects being dropped onto a target.
Configurer	getConfigurer() Get the Configurer object for this entity.
java.lang.String	getConfigureSource() Return the input source that was specified the last time the configure method was called.
java.lang.String	getConfigureText() Return the text string that represents the current configuration of this object.
ComponentPort	getIncomingPort() Return the incoming port.
NamedObj	getObjectInRefinement(java.lang.String name) Get a NamedObj with the given name in the refinement of this state, if any.
ComponentPort	getOutgoingPort() Return the outgoing port.
TypedActor[]	getRefinement() Return the refinements of this state.
java.util.List	nonpreemptiveTransitionList() Return the list of non-preemptive outgoing transitions from this state.
java.util.List	preemptiveTransitionList() Return the list of preemptive outgoing transitions from this state.

Methods inherited from class ptolemy.kernel.ComponentEntity

_addPort, _adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, newPort, propagateExistence, setContainer, setName

Methods inherited from class ptolemy.kernel.Entity

_description, _removePort, _validateSettables, connectedPortList, connectedPorts, connectionsChanged, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

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

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getDisplayName, getFullName, getName, getName

Field Detail

incomingPort

public ComponentPort incomingPort

The port linking incoming transitions.

isFinalState

public Parameter isFinalState

An indicator of whether this state is a final state. This is a boolean that defaults to false. Setting it to true will cause the containing FSMActor to return false from its postfire() method, which indicates to the director that the FSMActor should not be fired again.

isInitialState

public Parameter isInitialState

An indicator of whether this state is the initial state. This is a boolean that defaults to false, unless this state is the only one in the container, in which case it defaults to true. Setting it to true will cause this parameter to become false for whatever other state is currently the initial state in the same container.

outgoingPort

public ComponentPort outgoingPort

The port linking outgoing transitions.

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.

saveRefinementsInConfigurer

public Parameter saveRefinementsInConfigurer

A boolean attribute to decide refinements of this state should be exported as configurations of this state or not.

_configureSource

private java.lang.String _configureSource

_configurer

private Configurer _configurer

_nonpreemptiveTransitionList

private java.util.List _nonpreemptiveTransitionList

_preemptiveTransitionList

private java.util.List _preemptiveTransitionList

_refinement

private TypedActor[] _refinement

_refinementVersion

private long _refinementVersion

_transitionListVersion

private long _transitionListVersion

Constructor Detail

State

public State(CompositeEntity container,
             java.lang.String name)
      throws IllegalActionException,
             NameDuplicationException

Construct a state with the given name contained by the specified composite entity. The container argument must not be null, or a NullPointerException will be thrown. This state 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. Increment the version of the workspace. This constructor write-synchronizes on the workspace.

Parameters:

container - The container.

name - The name of the state.

Throws:

IllegalActionException - If the state cannot be contained by the proposed container.

NameDuplicationException - If the name coincides with that of an entity 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 refinementName attribute, record the change but do not check whether there is a TypedActor with the specified name and having the same container as the FSMActor containing this state.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If thrown by the superclass attributeChanged() method.

clone

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

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

Overrides:

clone in class ComponentEntity

Parameters:

workspace - The workspace for the new state.

Returns:

A new state.

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)

configure

public void configure(java.net.URL base,
                      java.lang.String source,
                      java.lang.String text)
               throws java.lang.Exception

Configure the object with data from the specified input source (a URL) and/or textual data. The object should interpret the source first, if it is specified, followed by the literal text, if that is specified. The new configuration should usually override any old configuration wherever possible, in order to ensure that the current state can be successfully retrieved.

This method is defined to throw a very general exception to allow classes that implement the interface to use whatever exceptions are appropriate.

Specified by:

configure in interface Configurable

Parameters:

base - The base relative to which references within the input are found, or null if this is not known, or there is none.

source - The input source, which specifies a URL, or null if none.

text - Configuration information given as text, or null if none.

Throws:

java.lang.Exception - If something goes wrong.

dropObject

public void dropObject(NamedObj target,
                       java.util.List dropObjects,
                       java.lang.String moml)
                throws IllegalActionException

React to a list of objects being dropped onto a target.

Specified by:

dropObject in interface DropTargetHandler

Parameters:

target - The target on which the objects are dropped.

dropObjects - The list of objects dropped onto the target.

moml - The moml string generated for the dropped objects.

Throws:

IllegalActionException - If the handling is unsuccessful.

getConfigureSource

public java.lang.String getConfigureSource()

Return the input source that was specified the last time the configure method was called.

Specified by:

getConfigureSource in interface Configurable

Returns:

The string representation of the input URL, or null if the no source has been used to configure this object, or null if no external source need be used to configure this object.

getConfigureText

public java.lang.String getConfigureText()

Return the text string that represents the current configuration of this object. Note that any configuration that was previously specified using the source attribute need not be represented here as well.

Specified by:

getConfigureText in interface Configurable

Returns:

A configuration string, or null if no configuration has been used to configure this object, or null if no configuration string need be used to configure this object.

getConfigurer

public Configurer getConfigurer()

Get the Configurer object for this entity.

Specified by:

getConfigurer in interface ConfigurableEntity

Returns:

the Configurer object for this entity.

getIncomingPort

public ComponentPort getIncomingPort()

Return the incoming port.

Specified by:

getIncomingPort in interface Flowable

Returns:

The incoming port.

getObjectInRefinement

public NamedObj getObjectInRefinement(java.lang.String name)
                               throws IllegalActionException

Get a NamedObj with the given name in the refinement of this state, if any.

Parameters:

name - The name of the NamedObj.

Returns:

The NamedObj in the refinement, or null if not found.

Throws:

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

getOutgoingPort

public ComponentPort getOutgoingPort()

Return the outgoing port.

Specified by:

getOutgoingPort in interface Flowable

Returns:

The outgoing port.

getRefinement

public TypedActor[] getRefinement()
                           throws IllegalActionException

Return the refinements of this state. 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.

nonpreemptiveTransitionList

public java.util.List nonpreemptiveTransitionList()

Return the list of non-preemptive outgoing transitions from this state.

Returns:

The list of non-preemptive outgoing transitions from this state.

preemptiveTransitionList

public java.util.List preemptiveTransitionList()

Return the list of preemptive outgoing transitions from this state.

Returns:

The list of preemptive outgoing transitions from this state.

_exportMoMLContents

protected void _exportMoMLContents(java.io.Writer output,
                                   int depth)
                            throws java.io.IOException

Write a MoML description of the contents of this object, which in this class are the attributes plus the ports. This method is called by exportMoML(). Each description is indented according to the specified depth and terminated with a newline character.

Overrides:

_exportMoMLContents in class Entity

Parameters:

output - The output to write to.

depth - The depth in the hierarchy, to determine indenting.

Throws:

java.io.IOException - If an I/O error occurs.

See Also:

NamedObj.exportMoML(Writer, int)

_populateRefinements

private void _populateRefinements()
                           throws IllegalActionException

Move the refinements in the configurer of this state to the closest modal model above this state in the model hierarchy.

Throws:

IllegalActionException

_updateTransitionLists

private void _updateTransitionLists()

Update the cached transition lists. This method is read-synchronized on the workspace.