cs101.lang
Class AnimatorThread

java.lang.Object
  java.lang.Thread
      cs101.lang.AnimatorThread

All Implemented Interfaces:

java.lang.Runnable

public final class AnimatorThread

extends java.lang.Thread

This class replaces Thread as a way to animate autonomous objects. An AnimatorThread can be passed any object that implements the Animate interface. The AnimatorThread (when started) begins executing at the Animate's act() method. Instances of this class provide safe ways to start, stop, suspend, and resume execution through the use of startExecution(), stopExecution(), suspendExecution() and resumeExecution() methods. Unlike java.lang.Thread, this class cannot be extended. Copyright 1999 Massachusetts Institute of Technology

Version:

$Id: AnimatorThread.java,v 1.5 2003/09/23 15:31:11 gus Exp $

Author:

Lynn Andrea Stein, las@ai.mit.edu

See Also:

Thread, Animate, startExecution(), stopExecution(), suspendExecution(), resumeExecution()

Field Summary

static boolean	DONT_START_YET These constants allow mnemonic access to AnimateObject's final constructor argument, i.e., should the object start running on construction or on (a subsequent) call to a separate start() method?
static boolean	START_IMMEDIATELY These constants allow mnemonic access to AnimateObject's final constructor argument, i.e., should the object start running on construction or on (a subsequent) call to a separate start() method?

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

AnimatorThread(Animate a)
This constructor requires the Animate that is to be animated.

AnimatorThread(Animate a, boolean startImmediately)
This constructor requires the Animate that is to be animated and a boolean value (expected to be one of AnimatorThread.START_IMMEDIATELY or AnimatorThread.DONT_START_YET) that determines whether this AnimatorThread should start running as the last step of its construction.

AnimatorThread(Animate a, boolean startImmediately, long sleepRange)
This constructor requires the Animate that is to be animated, a boolean reflecting whether execution should begin immediately, and a long representing the desired variance in sleep times between calls to the Animate's act() method.

AnimatorThread(Animate a, boolean startImmediately, long sleepRange, long sleepMinInterval)
This constructor requires the Animate that is to be animated, a boolean reflecting whether execution should begin immediately, and two longs representing the desired variance in sleep times and the desired minimum sleep interval between calls to the Animate's act() method.

AnimatorThread(Animate a, long sleepRange)
This constructor requires the Animate that is to be animated and a long representing the desired variance in sleep times between calls to the Animate's act() method.

AnimatorThread(Animate a, long sleepRange, long sleepMinInterval)
This constructor requires the Animate that is to be animated and two longs representing the desired variance in sleep times and the desired minimum sleep interval between calls to the Animate's act() method.

Method Summary

void	resumeExecution() Resumes execution after a temporary suspension (using suspendExecution()).
void	run() Repeatedly invoke your Animate's act() method, sleeping between invocations.
void	setSleepMinInterval(long minInterval) Gives access to this AnimatorThread's sleep minimum.
void	setSleepRange(long range) This controls the possible range of durations for AnimatorThread to sleep, i.e., the possible time between actions for the Animate that it animates.
void	start() Begin execution.
void	startExecution() Begin execution.
void	stopExecution() Terminates execution.
void	suspendExecution() Temporarily suspends execution.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

START_IMMEDIATELY

public static final boolean START_IMMEDIATELY

These constants allow mnemonic access to AnimateObject's final constructor argument, i.e., should the object start running on construction or on (a subsequent) call to a separate start() method?

See Also:

AnimatorThread( Animate, boolean ), Constant Field Values

DONT_START_YET

public static final boolean DONT_START_YET

These constants allow mnemonic access to AnimateObject's final constructor argument, i.e., should the object start running on construction or on (a subsequent) call to a separate start() method?

See Also:

AnimatorThread( Animate, boolean ), Constant Field Values

Constructor Detail

AnimatorThread

public AnimatorThread(Animate a)

This constructor requires the Animate that is to be animated. Once the AnimatorThread being constructed is started (using its start() method), the Animate's act() method will be called periodically, with the interval between calls controlled by sleepMinInterval and sleepRange.

Parameters:

a - the Animate to be animated.

See Also:

Animate, start(), setSleepMinInterval(long), setSleepRange( long )

AnimatorThread

public AnimatorThread(Animate a,
                      boolean startImmediately)

This constructor requires the Animate that is to be animated and a boolean value (expected to be one of AnimatorThread.START_IMMEDIATELY or AnimatorThread.DONT_START_YET) that determines whether this AnimatorThread should start running as the last step of its construction. If this boolean's value is START_IMMEDIATELY, execution will begin as soon as this constructor exits. Otherwise, a subsequent call to the AnimatorThread's start() method is required. It is expected that this boolean will generally be AnimatorThread.START_IMMEDIATELY as the default value of the one-arg constructor is AnimatorThread.DONT_START_YET.

Parameters:

a - the Animate to be animated.

startImmediately - one of AnimatorThread.START_IMMEDIATELY or AnimatorThread.DONT_START_YET

See Also:

Animate, AnimatorThread( Animate ), start(), setSleepMinInterval(long), setSleepRange( long )

AnimatorThread

public AnimatorThread(Animate a,
                      long sleepRange)

This constructor requires the Animate that is to be animated and a long representing the desired variance in sleep times between calls to the Animate's act() method. This constructor requires an additional call to the AnimatorThread's start() method. The sleep time between calls to the Animate's act() will vary between this.sleepMinInterval and this.sleepMinInterval + sleepRange.

Parameters:

a - the Animate to be animated.

sleepRange - the desired variance in sleep times above and beyond sleepMinInterval

See Also:

Animate, AnimatorThread( Animate ), start(), setSleepMinInterval(long), setSleepRange( long )

AnimatorThread

public AnimatorThread(Animate a,
                      boolean startImmediately,
                      long sleepRange)

This constructor requires the Animate that is to be animated, a boolean reflecting whether execution should begin immediately, and a long representing the desired variance in sleep times between calls to the Animate's act() method.

Parameters:

a - the Animate to be animated.

startImmediately - one of AnimatorThread.START_IMMEDIATELY or AnimatorThread.DONT_START_YET

sleepRange - the desired variance in sleep times above and beyond sleepMinInterval

See Also:

Animate, AnimatorThread( Animate, boolean ), AnimatorThread( Animate, long ), start(), setSleepMinInterval(long), setSleepRange( long )

AnimatorThread

public AnimatorThread(Animate a,
                      long sleepRange,
                      long sleepMinInterval)

This constructor requires the Animate that is to be animated and two longs representing the desired variance in sleep times and the desired minimum sleep interval between calls to the Animate's act() method. This constructor requires an additional call to the AnimatorThread's start() method. The sleep time between calls to the Animate's act() will vary between sleepMinInterval and sleepMinInterval + sleepRange.

Parameters:

a - the Animate to be animated.

sleepRange - the desired variance in sleep times above and beyond sleepMinInterval

sleepMinInterval - the minimum interval between calls to the Animate's act() method

See Also:

Animate, AnimatorThread( Animate ), start(), setSleepMinInterval(long), setSleepRange( long )

AnimatorThread

public AnimatorThread(Animate a,
                      boolean startImmediately,
                      long sleepRange,
                      long sleepMinInterval)

This constructor requires the Animate that is to be animated, a boolean reflecting whether execution should begin immediately, and two longs representing the desired variance in sleep times and the desired minimum sleep interval between calls to the Animate's act() method.

Parameters:

a - the Animate to be animated.

startImmediately - one of AnimatorThread.START_IMMEDIATELY or AnimatorThread.DONT_START_YET

sleepRange - the desired variance in sleep times above and beyond sleepMinInterval

sleepMinInterval - the minimum interval between calls to the Animate's act() method

See Also:

Animate, AnimatorThread( Animate, boolean ), AnimatorThread( Animate, long, long ), start(), setSleepMinInterval(long), setSleepRange( long )

Method Detail

run

public void run()

Repeatedly invoke your Animate's act() method, sleeping between invocations. This method contains an amazing amount of hair to deal with suspension, resumption, and stopping of AnimatorThreads. See theJavaSoft statement on Thread primitive deprication.

See Also:

Animate, setSleepMinInterval(long), setSleepRange( long )

start

public void start()

Begin execution. This causes the AnimatorThread to periodically call its Animate's act() method. (Same as this.startExecution().)

See Also:

Animate, AnimatorThread(Animate), Thread.start()

startExecution

public void startExecution()

Begin execution. This causes the AnimatorThread to periodically call its Animate's act() method.

See Also:

Animate, AnimatorThread(Animate), Thread.start()

stopExecution

public void stopExecution()

Terminates execution. This causes the AnimatorThread to cease execution immediately. Once stopped, an AnimatorThread cannot be restarted. Safely replaces Thread's (deprecated) stop() method.

See Also:

Thread.stop()

suspendExecution

public void suspendExecution()

Temporarily suspends execution. This causes the AnimatorThread to suspend execution following the next act() of its Animate. Periodic execution of the Animate's act() method can be restarted using resumeExecution(). Safely replaces Thread's (deprecated) suspend() method.

See Also:

resumeExecution(), Thread.suspend()

resumeExecution

public void resumeExecution()

Resumes execution after a temporary suspension (using suspendExecution()). Safely replaces Thread's (deprecated) resume() method.

See Also:

suspendExecution(), Thread.resume()

setSleepMinInterval

public void setSleepMinInterval(long minInterval)

Gives access to this AnimatorThread's sleep minimum. This controls the smallest interval for which this AnimatorThread will sleep, i.e., the minimum time between actions for the Animate that it animates. If sleepMinInterval is set to 0, it is possible that this AnimatorThread will prevent execution by other Threads by fully occupying the CPU.

See Also:

AnimatorThread( Animate, boolean, long, long ), setSleepRange( long )

setSleepRange

public void setSleepRange(long range)

This controls the possible range of durations for AnimatorThread to sleep, i.e., the possible time between actions for the Animate that it animates. In no case will the minimum sleep time be less than this.sleepMinInterval; it could be as long as this.sleepMinInterval + this.sleepRange. Gives access to this AnimatorThread's sleep variance. If 0, this AnimatorThread will sleep for the same amount of time between each invocation of the Animate's act() method.

See Also:

AnimatorThread( Animate, boolean, long, long ), setSleepRange( long )