ptolemy.actor

Class LocalClock

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.kernel.util.AbstractSettableAttribute

ptolemy.actor.LocalClock

All Implemented Interfaces:

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

public class LocalClock
extends AbstractSettableAttribute

A clock that keeps track of model time at a level of the model hierarchy and relates it to the time of the enclosing model, if there is one. The time of the enclosing model is referred to as the environment time. This clock has a notion of local time and committed time. The committed time is "simultaneous" with the environment time.

The local time is not allowed to move backwards past the committed time, but ahead of that time, it can move around at will.

There is no way of explicitly committing time, but several methods have the side effect of committing the current local time. For example, setClockDrift(double) will commit the current local time and change the clock drift. So will start() and stop()

This class implements the AbstractSettableAttribute interface because we want the localClock to be shown as a parameter in the editor dialogue of a director. A better implementation would be to derive LocalClock from Attribute and make changes to vergil such that Attributes are displayed in the dialogue, however, for the moment, the required changes are too complex. The value of the clock is exposed as an attribute that, by default, is non editable. The clock drift is a contained attribute that can be modified.

This class also specifies a globalTimeResolution parameter. This is a double with default 1E-10, which is 10^-10. All time values are rounded to the nearest multiple of this value. If the value is changed during a run, an exception is thrown. This is a shared parameter, which means that all instances of Director in the model will have the same value for this parameter. Changing one of them changes all of them.

FIXME: Setting of clock drift must be controlled because it commits time.

Since:

Ptolemy II 10.0

Version:

$Id$

Author:

Ilge Akkaya, Patricia Derler, Edward A. Lee, Christos Stergiou, Michael Zimmer

Pt.AcceptedRating:

red (eal)

Pt.ProposedRating:

yellow (eal)

Nested Class Summary

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	clockDrift The drift of the local clock with respect to the environment clock.
SharedParameter	globalTimeResolution The time precision used by this director.

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
LocalClock(NamedObj container, java.lang.String name) Construct an attribute with the given name contained by the specified entity.

Method Summary

Modifier and Type	Method and Description
void	addValueListener(ValueListener listener) This method has to be implemented for the AbstractSettableAttribute interface.
void	attributeChanged(Attribute attribute) Delegate the call to the director, which handles changes to the parameters of the clock.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
double	getClockDrift() Get clock drift.
Time	getEnvironmentTimeForLocalTime(Time time) Get the environment time that corresponds to the given local time.
java.lang.String	getExpression() Return the local time.
Time	getLocalTime() Get current local time.
Time	getLocalTimeForCurrentEnvironmentTime() Get the local time that corresponds to the current environment time.
Time	getLocalTimeForEnvironmentTime(Time time) Get the local time that corresponds to the given environment time.
double	getTimeResolution() Get the time resolution of the model.
Settable.Visibility	getVisibility() The LocalClock is not editable, thus visibility is always set to NOT_EDITABLE.
void	initialize() Initialize parameters that cannot be initialized in the constructor.
void	removeValueListener(ValueListener listener) This method has to be implemented for the AbstractSettableAttribute interface.
void	resetLocalTime(Time time) Set local time and commit.
void	setClockDrift(double drift) Set the new clock drift and commit it.
void	setLocalTime(Time time) Set local time without committing.
void	setTimeResolution(double timeResolution) Set time resolution.
void	setVisibility(Settable.Visibility visibility) This method has to be implemented for the AbstractSettableAttribute interface.
void	start() Start the clock with the current drift as specified by the last call to setClockDrift(double).
void	stop() Stop the clock.
java.util.Collection	validate() This method has to be implemented for the AbstractSettableAttribute interface.

Methods inherited from class ptolemy.kernel.util.AbstractSettableAttribute

getDefaultExpression, getValueAsString, setExpression

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setContainer, 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.Settable

getDisplayName

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getFullName, getName, getName, setName

Field Detail

globalTimeResolution

public SharedParameter globalTimeResolution

The time precision used by this director. All time values are rounded to the nearest multiple of this number. This is a double that defaults to "1E-10" which is 10^-10. This is a shared parameter, meaning that changing one instance in a model results in all instances being changed.

clockDrift

public Parameter clockDrift

The drift of the local clock with respect to the environment clock. If this is a top level director the clock drift has no consequence. The value is a double that is initialized to 1.0 which means that the local clock drift matches the one of the environment.

Constructor Detail

LocalClock

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

Construct an attribute with the given name contained by the specified entity. The container argument must not be null, or a NullPointerException will be thrown. This attribute 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.

Parameters:

container - The container.

name - The name of this attribute.

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

addValueListener

public void addValueListener(ValueListener listener)

This method has to be implemented for the AbstractSettableAttribute interface. This interface is only needed for the LocalClock to show up in the configuration dialogue of the container (the director). The method will not be used for this class so the implementation is empty.

Parameters:

listener - The listener to be added.

See Also:

removeValueListener(ValueListener)

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Delegate the call to the director, which handles changes to the parameters of the clock.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the director throws it.

clone

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

Clone the object into the specified workspace.

Overrides:

clone in class Attribute

Parameters:

workspace - The workspace for the cloned object.

Returns:

The cloned object.

Throws:

java.lang.CloneNotSupportedException - If thrown by super class.

See Also:

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

getClockDrift

public double getClockDrift()

Get clock drift.

Returns:

The clock drift.

See Also:

setClockDrift(double)

getEnvironmentTimeForLocalTime

public Time getEnvironmentTimeForLocalTime(Time time)
                                    throws IllegalActionException

Get the environment time that corresponds to the given local time. The given local time is required to be either equal to or greater than the committed time when this method is called.

Parameters:

time - The local Time.

Returns:

The corresponding environment Time.

Throws:

IllegalActionException - If the specified local time is in the past, or if Time objects cannot be created.

getExpression

public java.lang.String getExpression()

Return the local time.

Returns:

The local time as a string value.

See Also:

Settable.setExpression(String)

getLocalTime

public Time getLocalTime()

Get current local time. If it has never been set, then this will return Time.NEGATIVE_INFINITY. The returned value may have been set by setLocalTime(Time).

Returns:

The current local time.

See Also:

setLocalTime(Time)

getLocalTimeForCurrentEnvironmentTime

public Time getLocalTimeForCurrentEnvironmentTime()
                                           throws IllegalActionException

Get the local time that corresponds to the current environment time. The current environment time is required to be greater than or equal to the environment time corresponding to the last committed local time.

Returns:

The corresponding local time.

Throws:

IllegalActionException - If Time objects cannot be created, or if the current environment time is less than the time corresponding to the last committed local time.

getLocalTimeForEnvironmentTime

public Time getLocalTimeForEnvironmentTime(Time time)
                                    throws IllegalActionException

Get the local time that corresponds to the given environment time. The given environment time is required to be greater than or equal to the environment time corresponding to the last committed local time.

Parameters:

time - The environment time.

Returns:

The corresponding local time.

Throws:

IllegalActionException - If the specified environment time is less than the environment time corresponding to the last committed local time, or if Time objects cannot be created.

getTimeResolution

public final double getTimeResolution()

Get the time resolution of the model. The time resolution is the value of the timeResolution parameter. This is the smallest time unit for the model.

Returns:

The time resolution of the model.

See Also:

setTimeResolution(double)

getVisibility

public Settable.Visibility getVisibility()

The LocalClock is not editable, thus visibility is always set to NOT_EDITABLE.

Returns:

NOT_EDITABLE.

See Also:

Settable.setVisibility(Visibility)

initialize

public void initialize()

Initialize parameters that cannot be initialized in the constructor. For instance, Time objects cannot be created in the constructor because the time resolution might not be known yet. Older models have the timeResolution parameter specified in the director which will only be loaded by the MOMLParser after the director is initialized.

removeValueListener

public void removeValueListener(ValueListener listener)

This method has to be implemented for the AbstractSettableAttribute interface. This interface is only needed for the LocalClock to show up in the configuration dialogue of the container (the director). The method will not be used for this class so the implementation is empty.

Parameters:

listener - The listener to be removed.

See Also:

addValueListener(ValueListener)

resetLocalTime

public void resetLocalTime(Time time)

Set local time and commit. This is allowed to set time earlier than the last committed local time.

Parameters:

time - The new local time.

setClockDrift

public void setClockDrift(double drift)
                   throws IllegalActionException

Set the new clock drift and commit it.

Parameters:

drift - New clock drift.

Throws:

IllegalActionException - If the specified drift is non-positive.

See Also:

getClockDrift()

setLocalTime

public void setLocalTime(Time time)
                  throws IllegalActionException

Set local time without committing. This is not allowed to set time earlier than the last committed local time.

Parameters:

time - The new local time.

Throws:

IllegalActionException - If the specified time is earlier than the current time.

See Also:

getLocalTime()

setTimeResolution

public void setTimeResolution(double timeResolution)

Set time resolution.

Parameters:

timeResolution - The new time resolution.

See Also:

getTimeResolution()

setVisibility

public void setVisibility(Settable.Visibility visibility)

This method has to be implemented for the AbstractSettableAttribute interface. This interface is only needed for the LocalClock to show up in the configuration dialogue of the container (the director). This method does not do anything because visibility is always NOT_EDITABLE.

Parameters:

visibility - The new visibility.

See Also:

getVisibility()

start

public void start()

Start the clock with the current drift as specified by the last call to setClockDrift(double). If setClockDrift(double) has never been called, then the drift is 1.0. This method commits current local time.

stop

public void stop()

Stop the clock. The current time will remain the same as its current value until the next call to start(). This method commits current local time.

validate

public java.util.Collection validate()
                              throws IllegalActionException

This method has to be implemented for the AbstractSettableAttribute interface. This interface is only needed for the LocalClock to show up in the configuration dialogue of the container (the director). The value of the LocalClock does not need validation, thus this method does not do anything.

Returns:

Null.

Throws:

IllegalActionException - Not thrown in this base class.