ptolemy.actor.lib

Class ExceptionManager

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.moml.MoMLModelAttribute

ptolemy.actor.lib.ExceptionManager

All Implemented Interfaces:

java.lang.Cloneable, ExecutionListener, Initializable, Changeable, Configurable, Debuggable, DebugListener, Derivable, ExceptionHandler, HierarchyListener, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class ExceptionManager
extends MoMLModelAttribute
implements ExceptionHandler, ExecutionListener, Initializable, HierarchyListener

The ExceptionManager catches exceptions and attempts to handle them with the specified policy. It notifies ExceptionSubscribers after an exception has occurred and again after the handling attempt. If the exception cannot be handled, the model Manager is informed.

Since:

Ptolemy II 10.0

Version:

$Id$

Author:

Elizabeth Latronico

Pt.AcceptedRating:

Red (beth)

Pt.ProposedRating:

Red (beth)

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	exceptionMessage The exception message from the caught exception.
StringParameter	policy The error handling policy to apply if an exception occurs.
StringParameter	statusMessage The latest action, if any, taken by the CatchExceptionAttribute.

Fields inherited from class ptolemy.moml.MoMLModelAttribute

_model, modelURL

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
ExceptionManager(NamedObj container, java.lang.String name) Create a model attribute with the specified container and name.

Method Summary

Modifier and Type	Method and Description
protected Initializable	_getInitializableContainer() Return the first Initializable encountered above this in the hierarchy that will be initialized (i.e., it is either an atomic actor or an opaque composite actor).
void	addInitializable(Initializable initializable) Add the specified object to the set of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
void	executionError(Manager manager, java.lang.Throwable throwable) Do nothing upon execution error.
void	executionFinished(Manager manager) Restart here if restart is desired.
boolean	handleException(NamedObj context, java.lang.Throwable exception) Handle an exception according to the specified policy: continue: Not implemented yet Consume the exception and return control to the director.
void	hierarchyChanged() Notify this object that the containment hierarchy above it has changed.
void	hierarchyWillChange() Notify this object that the containment hierarchy above it will be changed.
void	initialize() Find all of the ExceptionSubscribers in the model and save in a list.
void	managerStateChanged(Manager manager) React to a change of state in the Manager.
void	preinitialize() Register this attribute with the manager.
void	removeInitializable(Initializable initializable) Remove the specified object from the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.
void	setContainer(NamedObj container) Override the base class to register as an Initializable so that preinitialize() is invoked, and as a HierarchyListener, so that we are notified of changes in the hierarchy above.
void	wrapup() Invoke wrapup() on registered initializables.

Methods inherited from class ptolemy.moml.MoMLModelAttribute

_exportMoMLContents, attributeChanged, configure, getConfigureSource, getConfigureText, getContainedModel

Methods inherited from class ptolemy.kernel.util.Attribute

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

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _description, _executeChangeRequests, _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

Methods inherited from interface ptolemy.kernel.util.Nameable

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

Field Detail

exceptionMessage

public StringParameter exceptionMessage

The exception message from the caught exception.

policy

public StringParameter policy

The error handling policy to apply if an exception occurs. One of: restart, stop, throw. See CatchExceptionAttribute

statusMessage

public StringParameter statusMessage

The latest action, if any, taken by the CatchExceptionAttribute. For example, a notification that the model has restarted. It offers a way to provide feedback to the user.

Constructor Detail

ExceptionManager

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

Create a model attribute with the specified container and name.

Parameters:

container - The specified container.

name - The specified name.

Throws:

IllegalActionException - If the attribute is not of an acceptable class for the container, or if the name contains a period.

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

Method Detail

addInitializable

public void addInitializable(Initializable initializable)

Add the specified object to the set of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object.

Specified by:

addInitializable in interface Initializable

Parameters:

initializable - The object whose methods should be invoked.

See Also:

removeInitializable(Initializable)

clone

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

Clone the object into the specified workspace.

Overrides:

clone in class MoMLModelAttribute

Parameters:

workspace - The workspace for the new object.

Returns:

A new NamedObj.

Throws:

java.lang.CloneNotSupportedException - If any of the attributes cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

executionError

public void executionError(Manager manager,
                           java.lang.Throwable throwable)

Do nothing upon execution error. Exceptions are passed to this attribute through handleException(). This method is required by the ExecutionListener interface.

Specified by:

executionError in interface ExecutionListener

Parameters:

manager - The manager controlling the execution.

throwable - The throwable to report.

executionFinished

public void executionFinished(Manager manager)

Restart here if restart is desired. This method is called upon successful completion.

Specified by:

executionFinished in interface ExecutionListener

Parameters:

manager - The manager controlling the execution.

hierarchyChanged

public void hierarchyChanged()
                      throws IllegalActionException

Notify this object that the containment hierarchy above it has changed. This method does nothing because instead we use preinitialize() to handle re-establishing the connections.

Specified by:

hierarchyChanged in interface HierarchyListener

Throws:

IllegalActionException - If the change is not acceptable.

See Also:

AbstractInitializableAttribute

hierarchyWillChange

public void hierarchyWillChange()
                         throws IllegalActionException

Notify this object that the containment hierarchy above it will be changed.

Specified by:

hierarchyWillChange in interface HierarchyListener

Throws:

IllegalActionException - If unlinking to a published port fails.

See Also:

AbstractInitializableAttribute

initialize

public void initialize()
                throws IllegalActionException

Find all of the ExceptionSubscribers in the model and save in a list.

Specified by:

initialize in interface Initializable

Throws:

IllegalActionException - If thrown by parent

handleException

public boolean handleException(NamedObj context,
                               java.lang.Throwable exception)
                        throws IllegalActionException

Handle an exception according to the specified policy: continue: Not implemented yet Consume the exception and return control to the director. Could be valuable for domains like DE or modal models when new events will arrive. Probably not appropriate for domains like SDF where the director follows a predefined schedule based on data flow (since the actor throwing the exception no longer provides output to the next actor). throw: Do not catch the exception. restart: Stop and restart the model. Does not apply to exceptions generated during initialize(). stop: Stop the model.

Specified by:

handleException in interface ExceptionHandler

Parameters:

context - The object in which the error occurred.

exception - The exception to be handled.

Returns:

true if the exception is handled; false if this attribute did not handle it

Throws:

IllegalActionException - If thrown by the parent

managerStateChanged

public void managerStateChanged(Manager manager)

React to a change of state in the Manager.

Specified by:

managerStateChanged in interface ExecutionListener

Parameters:

manager - The model manager

See Also:

Manager.getState()

removeInitializable

public void removeInitializable(Initializable initializable)

Remove the specified object from the list of objects whose preinitialize(), initialize(), and wrapup() methods should be invoked upon invocation of the corresponding methods of this object. If the specified object is not on the list, do nothing.

Specified by:

removeInitializable in interface Initializable

Parameters:

initializable - The object whose methods should no longer be invoked.

See Also:

addInitializable(Initializable)

preinitialize

public void preinitialize()
                   throws IllegalActionException

Register this attribute with the manager. Done here instead of in the constructor since the director is found in order to get the manager. The constructor for this attribute might be called before the constructor for the director.

Specified by:

preinitialize in interface Initializable

Throws:

IllegalActionException - If the parent class throws it

setContainer

public void setContainer(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException

Override the base class to register as an Initializable so that preinitialize() is invoked, and as a HierarchyListener, so that we are notified of changes in the hierarchy above.

Overrides:

setContainer in class Attribute

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If the action would result in a recursive containment structure, or if this entity and container are not in the same workspace.

NameDuplicationException - If the container already has an entity with the name of this entity.

See Also:

AbstractInitializableAttribute

wrapup

public void wrapup()
            throws IllegalActionException

Invoke wrapup() on registered initializables.

Specified by:

wrapup in interface Initializable

Throws:

IllegalActionException - If thrown by a subclass.

See Also:

AbstractInitializableAttribute

_getInitializableContainer

protected Initializable _getInitializableContainer()

Return the first Initializable encountered above this in the hierarchy that will be initialized (i.e., it is either an atomic actor or an opaque composite actor).

Returns:

The first Initializable above this in the hierarchy, or null if there is none.

See Also:

AbstractInitializableAttribute