ptolemy.data.properties
Class PropertySolverBase

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.data.properties.PropertySolverBase

All Implemented Interfaces:

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

Direct Known Subclasses:

PropertySolver

public abstract class PropertySolverBase
extends Attribute

The base abstract class for a property solver.

The base class provides the core functionality for property resolution. It provides a method to create a PropertyHelper for any given model component. The model component can be an object of any Ptolemy class (e.g. ASTPtRootNode, Sink, Entity, and FSMActor). A model component, in turn, may have one or multiple property-able objects.

A PropertySolver is associated with strictly one use-case. PropertySolvers with the same use-case are considered equivalent. Subclasses need to associate the solver with an unique use-case by providing implementation for getUseCaseName(), getExtendedUseCaseName(). An use-case may have dependency with other use-cases. The dependencies are declared when the solver is instantiated. The dependencies needs to be kept non-circular to avoid non-deterministic resolution result.

Every PropertySolver is linked together by the SharedParameter called "sharedUtilitiesWrapper", which contains the shared utility object. This allows every PropertySolver to find other solvers in the model.

Subclasses needs to implement resolveProperties() to specify exactly how to perform the property resolution. For example, one may gather all the constraints from the PropertyHelpers and feed them into a constraint solver.

Since:

Ptolemy II 7.1

Version:

$Id: PropertySolverBase.java 55414 2009-08-08 19:44:27Z cxh $

Author:

Man-Kit Leung

See Also:

Serialized Form

Accepted Rating:

Red (mankit)

Proposed Rating:

Red (mankit)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

protected java.util.List<java.lang.String>	_dependentUseCases The list that keeps track of the dependencies on other use-cases.
private StringBufferExec	_executeCommands
protected java.util.HashMap<java.lang.Object,PropertyHelper>	_helperStore The HashMap that caches components and their PropertyHelper objects.
protected java.util.HashSet<java.lang.Object>	_nonSettables The set of property-able objects that have non-settable property.
private static PtParser	_parser The expression parser.
protected java.util.HashMap<java.lang.Object,Property>	_resolvedProperties The HashMap that caches property-able objects and their Property values.
protected SharedUtilities	_sharedUtilities The utilities shared between all solvers.
SharedParameter	sharedUtilitiesWrapper The shared parameter that links together every solver in the same model.

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

PropertySolverBase(NamedObj container, java.lang.String name)
Construct a PropertySolverBase with the specified container and name.

Method Summary

private void	_compileHelperClasses()
private void	_compileUserCode(Entity entity, java.lang.String userCode)
protected PropertyHelper	_getHelper(java.lang.Object component) Return the PropertyHelper for the specified component.
protected java.lang.String	_getPackageName() Return the package name that contains the class of this solver.
protected NamedObj	_toplevel()
void	addDependentUseCase(java.lang.String userCaseName) Add the given unique solver (user-case) identifier to the dependency list.
void	clearResolvedProperty(java.lang.Object object) Clear the resolved property for the specified object.
PropertySolver	findSolver(java.lang.String identifier) Find a solver that is associated with the specified label.
java.util.List<PropertyHelper>	getAllHelpers() Return the list of all PropertyHelpers associated with this solver.
java.util.Set	getAllPropertyables() Return the set of all property-able objects obtained from all PropertyHelper.
static java.util.List<PropertySolver>	getAllSolvers(SharedParameter sharedParameter) Return the list of all solvers that are in the same model.
Attribute	getAttribute(ASTPtRootNode node) Get the attribute that corresponds to the specified ASTPtRootNode.
java.util.List<java.lang.String>	getDependentSolvers() Return the list of dependent solvers.
abstract java.lang.String	getExtendedUseCaseName() Return the extended use-case name.
PropertyHelper	getHelper(java.lang.Object object) Return the property helper for the specified component.
static PtParser	getParser() Return the expression parser.
ASTPtRootNode	getParseTree(Attribute attribute) Return the root ASTPtRootNode associated with the specified attribute.
Property	getProperty(java.lang.Object object) Return the property value associated with the specified object.
Property	getResolvedProperty(java.lang.Object object) Return the resolved property for the specified object.
Property	getResolvedProperty(java.lang.Object object, boolean resolve) Return the resolved property for the specified object.
SharedUtilities	getSharedUtilities() Return the shared utility object.
abstract java.lang.String	getUseCaseName() Return the use-case name.
void	markAsNonSettable(java.lang.Object object) Mark the property of the specified object as non-settable.
void	reset() Reset the solver.
void	resetAll() Reset every solver in the model.
abstract void	resolveProperties() Perform property resolution.
void	setResolvedProperty(java.lang.Object object, Property property) Set the resolved property of the specified object.

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, clone, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setContainer, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

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

Methods inherited from class java.lang.Object

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

Field Detail

sharedUtilitiesWrapper

public SharedParameter sharedUtilitiesWrapper

The shared parameter that links together every solver in the same model.

_dependentUseCases

protected java.util.List<java.lang.String> _dependentUseCases

The list that keeps track of the dependencies on other use-cases. Circular dependencies are not allowed but it is up to the user to enforce this requirement. This means that there should not be a case where two solvers' use-cases exist in each other's dependency list.

_helperStore

protected java.util.HashMap<java.lang.Object,PropertyHelper> _helperStore

The HashMap that caches components and their PropertyHelper objects.

_nonSettables

protected java.util.HashSet<java.lang.Object> _nonSettables

The set of property-able objects that have non-settable property. A non-settable property results from setting an object with a fixed property through PropertyHelper.setEquals().

_resolvedProperties

protected java.util.HashMap<java.lang.Object,Property> _resolvedProperties

The HashMap that caches property-able objects and their Property values. Each mapping is a pair of Object and Property.

_sharedUtilities

protected SharedUtilities _sharedUtilities

The utilities shared between all solvers.

_executeCommands

private StringBufferExec _executeCommands

_parser

private static PtParser _parser

The expression parser.

Constructor Detail

PropertySolverBase

public PropertySolverBase(NamedObj container,
                          java.lang.String name)
                   throws IllegalActionException,
                          NameDuplicationException

Construct a PropertySolverBase with the specified container and name. If this is the first PropertySolver created in the model, the shared utility object will also be created.

Parameters:

container - The specified container.

name - The specified name.

Throws:

IllegalActionException - If the PropertySolverBase is not of an acceptable attribute for the container.

NameDuplicationException - If the name coincides with an attribute already in the container.

Method Detail

addDependentUseCase

public void addDependentUseCase(java.lang.String userCaseName)

Add the given unique solver (user-case) identifier to the dependency list. A dependent solver is one whose analysis result is required for this solver's resolution. The dependent solvers are run in order before invoking this solver.

Parameters:

userCaseName - The specified user case name.

clearResolvedProperty

public void clearResolvedProperty(java.lang.Object object)

Clear the resolved property for the specified object. The object is assumed to be property-able; otherwise, nothing happens.

Parameters:

object - The specified object.

findSolver

public PropertySolver findSolver(java.lang.String identifier)
                          throws PropertyResolutionException

Find a solver that is associated with the specified label. A solver can be identified by the use-case name, class name, or its name in the model. There can be more than one solvers with the label. This method returns whichever it finds first.

Parameters:

identifier - The specified label.

Returns:

The property solver associated with the specified label.

Throws:

IllegalActionException - Thrown if no matched solver is found.

PropertyResolutionException

getAllHelpers

public java.util.List<PropertyHelper> getAllHelpers()
                                             throws IllegalActionException

Return the list of all PropertyHelpers associated with this solver.

Returns:

The list of PropertyHelpers.

Throws:

IllegalActionException

getAllPropertyables

public java.util.Set getAllPropertyables()
                                  throws IllegalActionException

Return the set of all property-able objects obtained from all PropertyHelper.

Returns:

The set of all property-able objects.

Throws:

IllegalActionException - Thrown if an error occurs when getting the helpers or the property-able objects from them.

getAllSolvers

public static java.util.List<PropertySolver> getAllSolvers(SharedParameter sharedParameter)

Return the list of all solvers that are in the same model. They are linked by the specified SharedParameter.

Parameters:

sharedParameter - The specified SharedParameter links together the solvers.

Returns:

A list of PropertySolvers.

getAttribute

public Attribute getAttribute(ASTPtRootNode node)

Get the attribute that corresponds to the specified ASTPtRootNode. This assumes that the correspondence is recorded previously through calling PropertyHelper.putAttribute(ASTPtRootNode, Attribute).

Parameters:

node - The specified ASTPtRootNode.

Returns:

The attribute associated with the specified ASTPtRootNode.

Throws:

java.lang.AssertionError - Thrown if the specified node does not have a corresponding attribute.

getDependentSolvers

public java.util.List<java.lang.String> getDependentSolvers()

Return the list of dependent solvers. The list contains the unique name of the solvers.

Returns:

The list of dependent solvers.

getExtendedUseCaseName

public abstract java.lang.String getExtendedUseCaseName()

Return the extended use-case name. The extended use-case name is an unique label for a use-case.

Returns:

the extended use-case name.

getHelper

public PropertyHelper getHelper(java.lang.Object object)
                         throws IllegalActionException

Return the property helper for the specified component.

Parameters:

object - The specified component.

Returns:

The property helper for the component.

Throws:

IllegalActionException - Thrown if the helper cannot be found or instantiated.

getParser

public static PtParser getParser()

Return the expression parser.

Returns:

The expression parser.

getParseTree

public ASTPtRootNode getParseTree(Attribute attribute)
                           throws IllegalActionException

Return the root ASTPtRootNode associated with the specified attribute.

Parameters:

attribute - The specified attribute.

Returns:

The root ASTPtRootNode associated with the specified attribute.

Throws:

IllegalActionException

getProperty

public Property getProperty(java.lang.Object object)

Return the property value associated with the specified object.

Parameters:

object - The specified object.

Returns:

The property of the specified object.

getResolvedProperty

public Property getResolvedProperty(java.lang.Object object)

Return the resolved property for the specified object. This forces resolution to happen if the object's property is not present.

Parameters:

object - The specified object

Returns:

The resolved property for the specified object.

getResolvedProperty

public Property getResolvedProperty(java.lang.Object object,
                                    boolean resolve)

Return the resolved property for the specified object. The specified resolve flag indicates whether to force resolution to happen.

Parameters:

object - The specified object.

resolve - Whether or not to force resolution.

Returns:

The resolved property for the specified object.

getSharedUtilities

public SharedUtilities getSharedUtilities()

Return the shared utility object.

Returns:

The shared utility object.

getUseCaseName

public abstract java.lang.String getUseCaseName()

Return the use-case name. The use-case name is not guaranteed to be unique.

Returns:

The use-case name.

markAsNonSettable

public void markAsNonSettable(java.lang.Object object)

Mark the property of the specified object as non-settable. The specified object has a fixed assigned property.

Parameters:

object - The specified object.

reset

public void reset()

Reset the solver.

resetAll

public void resetAll()

Reset every solver in the model.

resolveProperties

public abstract void resolveProperties()
                                throws KernelException

Perform property resolution.

Throws:

KernelException - Thrown if sub-class throws it.

setResolvedProperty

public void setResolvedProperty(java.lang.Object object,
                                Property property)

Set the resolved property of the specified object. (See getResolvedProperty(Object)).

Parameters:

object - The specified object.

property - The specified property.

_getHelper

protected PropertyHelper _getHelper(java.lang.Object component)
                             throws IllegalActionException

Return the PropertyHelper for the specified component. This instantiates a new PropertyHelper if it does not already exist for the specified component.

Parameters:

component - The specified component.

Returns:

The PropertyHelper for the specified component.

Throws:

IllegalActionException - Thrown if the PropertyHelper cannot be instantiated.

_getPackageName

protected java.lang.String _getPackageName()

Return the package name that contains the class of this solver.

Returns:

The package name.

_toplevel

protected NamedObj _toplevel()

_compileHelperClasses

private void _compileHelperClasses()
                            throws IllegalActionException

Throws:

IllegalActionException

_compileUserCode

private void _compileUserCode(Entity entity,
                              java.lang.String userCode)
                       throws IllegalActionException

Parameters:

entity -

userCode -

Throws:

IllegalActionException