Package ptolemy.actor.lib

Class CatchExceptionAttribute

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.actor.AbstractInitializableAttribute

ptolemy.actor.lib.CatchExceptionAttribute

All Implemented Interfaces:

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

Direct Known Subclasses:

AnalyzeExceptionAttribute

public class CatchExceptionAttribute
extends AbstractInitializableAttribute
implements ExceptionHandler, ExecutionListener

This attribute catches exceptions and attempts to handle them with the specified policy. If the exception cannot be handled, the attribute indicates this to the Manager. Status messages may be logged to a file.

Since:

Ptolemy II 10.0

Version:

$Id$

Author:

Edward A. Lee, 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	Description
static java.lang.String	CONTINUE	String value for the "continue" policy.
StringParameter	exceptionMessage	The exception message from the caught exception.
FileParameter	logFileName	The file, if any, to log messages to.
StringParameter	policy	The error handling policy to apply if an exception occurs.
static java.lang.String	RESTART	String value for the "restart" policy.
StringParameter	statusMessage	The latest action, if any, taken by the CatchExceptionAttribute.
static java.lang.String	STOP	String value for the "stop" policy.
static java.lang.String	THROW	String value for the "throw" policy.

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	Description
CatchExceptionAttribute(CompositeEntity container, java.lang.String name)	Create a new actor in the specified container with the specified name.

Method Summary

Modifier and Type	Method	Description
protected void	_writeMessage(java.lang.String message)	Write the given message to the statusMessage parameter and to the log file, if open.
void	attributeChanged(Attribute attribute)	React to a change in an attribute.
java.lang.Object	clone(Workspace workspace)	Clone the attribute 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	initialize()	Find all of the ExceptionSubscribers in the model.
void	managerStateChanged(Manager manager)	React to a change of state in the Manager.
void	preinitialize()	Register this attribute with the manager.

Methods inherited from class ptolemy.actor.AbstractInitializableAttribute

_getInitializableContainer, addInitializable, hierarchyChanged, hierarchyWillChange, removeInitializable, setContainer, wrapup

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, _exportMoMLContents, _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.

logFileName

public FileParameter logFileName

The file, if any, to log messages to.

policy

public StringParameter policy

The error handling policy to apply if an exception occurs. One of: Continue, Throw, Restart, Quit

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.

CONTINUE

public static final java.lang.String CONTINUE

String value for the "continue" policy.

See Also:

Constant Field Values

RESTART

public static final java.lang.String RESTART

String value for the "restart" policy.

See Also:

Constant Field Values

THROW

public static final java.lang.String THROW

String value for the "throw" policy.

See Also:

Constant Field Values

STOP

public static final java.lang.String STOP

String value for the "stop" policy.

See Also:

Constant Field Values

Constructor Detail

CatchExceptionAttribute

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

Create a new actor in the specified container with the specified name. The name must be unique within the container or an exception is thrown. The container argument must not be null, or a NullPointerException will be thrown.

Parameters:

container - The container.

name - The name of this actor within the container.

Throws:

IllegalActionException - If this actor cannot be contained by the proposed container (see the setContainer() method).

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

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

React to a change in an attribute. This method is called by a contained attribute when its value changes. In this base class, the method does nothing. In derived classes, this method may throw an exception, indicating that the new attribute value is invalid. It is up to the caller to restore the attribute to a valid value if an exception is thrown.

Overrides:

attributeChanged in class NamedObj

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 attribute into the specified workspace.

Overrides:

clone in class AbstractInitializableAttribute

Parameters:

workspace - The workspace for the new object.

Returns:

A new actor.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

Object.clone()

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

throwable - Ignored.

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 that starts the run.

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

initialize

public void initialize()
                throws IllegalActionException

Find all of the ExceptionSubscribers in the model.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AbstractInitializableAttribute

Throws:

IllegalActionException - If thrown by 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()

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

Overrides:

preinitialize in class AbstractInitializableAttribute

Throws:

IllegalActionException - If the parent class throws it

_writeMessage

protected void _writeMessage(java.lang.String message)
                      throws java.io.IOException

Write the given message to the statusMessage parameter and to the log file, if open.

Parameters:

message - The message to write

Throws:

java.io.IOException - If there is a problem writing to the file