ptolemy.data.expr

Class ConstraintMonitor

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.kernel.util.AbstractSettableAttribute

ptolemy.data.expr.Variable

ptolemy.data.expr.Parameter

ptolemy.data.expr.ConstraintMonitor

All Implemented Interfaces:

java.lang.Cloneable, HasTypeConstraints, Typeable, Changeable, Debuggable, DebugListener, Decorator, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable, Settable, ValueListener

public class ConstraintMonitor
extends Parameter
implements Decorator

A contract monitor that decorates each entity in a model with a value parameter and monitors the sum of all such values. If the sum of the values equals or exceeds the value given in threshold and warningEnabled is true, then this class will issue a warning when the aggregate value matches or exceeds the threshold. The decorator values default to 0.0, so the default total is 0.0. The default threshold is Infinity, so no warnings will be issued by default.

If the includeOpaqueContents parameter is true, then this decorator will also decorate entities within opaque composite actors. By default, this is false.

This object is a Parameter whose value is the total of the values of all the decorator values. To use it, simply drag it into a model.

Since:

Ptolemy II 10.0

Version:

$Id$

Author:

Edward A. Lee

Pt.AcceptedRating:

Red (eal)

Pt.ProposedRating:

Yellow (eal)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ConstraintMonitor.ConstraintMonitorAttributes Class containing the decorator attributes that decorate objects.

Nested classes/interfaces inherited from class ptolemy.data.expr.Variable

Variable.CircularDependencyError, Variable.VariableScope

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

NamedObj.ContainedObjectsIterator

Nested classes/interfaces inherited from interface ptolemy.kernel.util.Settable

Settable.Visibility

Field Summary

Fields

Modifier and Type	Field and Description
Parameter	includeOpaqueContents If true, then this decorator decorates entities within opaque composite actors.
Parameter	includeTransparents If true, then this decorator decorates transparent composite entities.
Parameter	threshold Threshold at which this monitor issues a warning, if warningEnabled is true.
Parameter	warningEnabled If true (the default), then a warning is issued when the aggregate value equals or exceeds the specified threshold.

Fields inherited from class ptolemy.data.expr.Variable

_currentExpression, _needsEvaluation, _parserScope, _parseTreeValid, _suppressVariableSubstitution, _valueListeners

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

Fields inherited from interface ptolemy.kernel.util.Settable

EXPERT, FULL, NONE, NOT_EDITABLE

Constructor Summary

Constructors

Constructor and Description
ConstraintMonitor(CompositeEntity container, java.lang.String name) Construct an instance in the given container with the given name.

Method Summary

Modifier and Type	Method and Description
protected void	_addAllContainedEntities(CompositeEntity container, java.util.List<NamedObj> result, boolean transparents, boolean opaques) Add to the specified list all contained entities of the specified container that are not class definitions.
protected boolean	_deepContains(CompositeEntity container, Entity target, boolean opaques) Return true if the specified target is deeply contained by the specified container subject to the constraints given by the opaques parameter.
protected void	_evaluate() Evaluate the current expression to a token, which in this case means to sum the values of all the decorated objects.
void	attributeChanged(Attribute attribute) Override the base class to invalidate if parameters have changed.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
DecoratorAttributes	createDecoratorAttributes(NamedObj target) Return the decorated attributes for the target NamedObj, or null if the target is not decorated by this decorator.
java.util.List<NamedObj>	decoratedObjects() Return a list of the entities deeply contained by the container of this resource scheduler.
Token	getToken() Override the base class to check whether the threshold constraint is satisfied.
void	invalidate() Override the base class to mark this as needing evaluation even though there is no expression.
boolean	isGlobalDecorator() Return the value of includeOpaqueContents.
java.util.Collection	validate() Override the base class to establish a connection with any decorated objects it finds in scope in the container.
void	valueChanged(Settable settable) Override the base class to mark that evaluation is needed regardless of the current expression.

Methods inherited from class ptolemy.data.expr.Parameter

addChoice, exportMoML, getChoices, removeAllChoices, removeChoice

Methods inherited from class ptolemy.data.expr.Variable

_description, _getCurrentExpression, _notifyValueListeners, _parseIfNecessary, _propagate, _propagateToValueListeners, _propagateValue, _setToken, _setTokenAndNotify, addValueListener, getDeclaredType, getExpression, getFreeIdentifiers, getParserScope, getScope, getScope, getType, getTypeTerm, getValueAsString, getVariable, getVisibility, isKnown, isLazy, isStringMode, isSuppressVariableSubstitution, isTypeAcceptable, removeValueListener, reset, setContainer, setExpression, setLazy, setName, setParseTreeEvaluator, setStringMode, setSuppressVariableSubstitution, setToken, setToken, setTypeAtLeast, setTypeAtLeast, setTypeAtMost, setTypeEquals, setTypeSameAs, setUnknown, setValueListenerAsWeakDependency, setVisibility, stringRepresentation, toString, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.kernel.util.AbstractSettableAttribute

getDefaultExpression

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, updateContent

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, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, 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, uniqueName, 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.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Settable

getDisplayName

Field Detail

includeOpaqueContents

public Parameter includeOpaqueContents

If true, then this decorator decorates entities within opaque composite actors. This is a boolean that defaults to false.

includeTransparents

public Parameter includeTransparents

If true, then this decorator decorates transparent composite entities. This is a boolean that defaults to false.

threshold

public Parameter threshold

Threshold at which this monitor issues a warning, if warningEnabled is true. This is a double that defaults to Infinity, meaning no constraint on the sum of the decorator values.

warningEnabled

public Parameter warningEnabled

If true (the default), then a warning is issued when the aggregate value equals or exceeds the specified threshold. This is a boolean that defaults to true.

Constructor Detail

ConstraintMonitor

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

Construct an instance in the given container with the given name. The container argument must not be null, or a NullPointerException will be thrown. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace.

Parameters:

container - The container, which contains the objects to be decorated

name - Name of this constraint monitor.

Throws:

IllegalActionException - If this object is not compatible with the specified container.

NameDuplicationException - If the name collides with an attribute in the container or if there is a name duplication during initialization.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Override the base class to invalidate if parameters have changed.

Overrides:

attributeChanged in class Variable

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

clone

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

Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there). The result is an object with no container.

Overrides:

clone in class Parameter

Parameters:

workspace - The workspace for the cloned object.

Returns:

The new object.

Throws:

java.lang.CloneNotSupportedException - Not thrown in this base class

See Also:

Object.clone()

createDecoratorAttributes

public DecoratorAttributes createDecoratorAttributes(NamedObj target)
                                              throws IllegalActionException

Return the decorated attributes for the target NamedObj, or null if the target is not decorated by this decorator. Specification, every Entity that is not a class definition that is contained (deeply) by the container of this decorator is decorated. This includes atomic entities and both opaque and transparent composite entities.

Specified by:

createDecoratorAttributes in interface Decorator

Parameters:

target - The NamedObj that will be decorated.

Returns:

The decorated attributes for the target NamedObj.

Throws:

IllegalActionException - If some object cannot be determined to be decorated or not (e.g., a parameter cannot be evaluated).

decoratedObjects

public java.util.List<NamedObj> decoratedObjects()
                                          throws IllegalActionException

Return a list of the entities deeply contained by the container of this resource scheduler. This includes all entities, whether transparent or opaque, including those inside opaque entities. It does not include entities that are class definitions.

Specified by:

decoratedObjects in interface Decorator

Returns:

A list of the objects decorated by this decorator.

Throws:

IllegalActionException - If some object cannot be determined to be decorated or not (e.g., a parameter cannot be evaluated).

isGlobalDecorator

public boolean isGlobalDecorator()
                          throws IllegalActionException

Return the value of includeOpaqueContents. decorate objects across opaque hierarchy boundaries.

Specified by:

isGlobalDecorator in interface Decorator

Returns:

True if decorator is global.

Throws:

IllegalActionException - If there is a problem getting the boolean valu from the includeOpaqueContents token.

getToken

public Token getToken()
               throws IllegalActionException

Override the base class to check whether the threshold constraint is satisfied.

Overrides:

getToken in class Variable

Returns:

The token contained by this variable converted to the type of this variable, or null if there is none.

Throws:

IllegalActionException - If the expression cannot be parsed or cannot be evaluated, or if the result of evaluation violates type constraints, or if the result of evaluation is null and there are variables that depend on this one.

See Also:

Variable.setToken(String), Variable.setToken(ptolemy.data.Token)

invalidate

public void invalidate()

Override the base class to mark this as needing evaluation even though there is no expression.

Overrides:

invalidate in class Variable

validate

public java.util.Collection validate()
                              throws IllegalActionException

Override the base class to establish a connection with any decorated objects it finds in scope in the container.

Specified by:

validate in interface Settable

Overrides:

validate in class Variable

Returns:

The current list of value listeners, which are evaluated as a consequence of this call to validate().

Throws:

IllegalActionException - If this variable or a variable dependent on this variable cannot be evaluated (and is not lazy) and the model error handler throws an exception. Also thrown if the change is not acceptable to the container.

valueChanged

public void valueChanged(Settable settable)

Override the base class to mark that evaluation is needed regardless of the current expression.

Specified by:

valueChanged in interface ValueListener

Overrides:

valueChanged in class Variable

Parameters:

settable - The object that has changed value.

_addAllContainedEntities

protected void _addAllContainedEntities(CompositeEntity container,
                                        java.util.List<NamedObj> result,
                                        boolean transparents,
                                        boolean opaques)

Add to the specified list all contained entities of the specified container that are not class definitions. This includes all the entities returned by CompositeEntity.deepEntityList(). If includeTransparents is true, then it also includes transparent composite entities. If includeOpaqueContents is true, then it also includes the entities contained within opaque composite entities.

Parameters:

container - The container of the entities.

result - The list to which to add the entities.

transparents - Specification of whether to include transparent composite entities.

opaques - Specification of whether to include the contents of opaque composite entities.

_deepContains

protected boolean _deepContains(CompositeEntity container,
                                Entity target,
                                boolean opaques)

Return true if the specified target is deeply contained by the specified container subject to the constraints given by the opaques parameter.

Parameters:

container - The container.

target - The object that may be contained by the container.

opaques - If true, then allow one or more intervening opaque composite actors in the hierarchy.

Returns:

True if the specified target is deeply contained by the container

_evaluate

protected void _evaluate()
                  throws IllegalActionException

Evaluate the current expression to a token, which in this case means to sum the values of all the decorated objects.

Overrides:

_evaluate in class Variable

Throws:

IllegalActionException - If the expression cannot be parsed or cannot be evaluated, or if a dependency loop is found.