de.myfoo.commonj.timers
Class FooTimerManager

java.lang.Object
  extended by de.myfoo.commonj.timers.FooTimerManager
All Implemented Interfaces:
commonj.timers.TimerManager, java.lang.Runnable

public final class FooTimerManager
extends java.lang.Object
implements commonj.timers.TimerManager, java.lang.Runnable

Implementation of the TimerManager. Each of the TimerManager schedule methods returns a Timer object. The returned Timer can then be queried and/or cancelled. Applications are required to implement the TimerListener interface and may optionally implement one or both of the CancelTimerListener and StopTimerListener interfaces.

All Timers execute in the same JVM as the thread that created the Timer and are transient. If the JVM fails then all Timers will be lost.

Recurring timers will execute their TimerListener multiple times. Invocations of the TimerListener are executed serially. That is, if a timer is scheduled to repeat every 5 seconds and a previous execution is still running, then the subsequent execution is delayed until the currently running execution completes.

A TimerListener scheduled multiple times, resulting in the return of multiple Timer instances, may execute concurrently depending on implementation. Proper thread safety techniques need to be employed.

Two types of repeating timers are available:

Version:
1.0
Author:
Andreas Keldenich
See Also:
TimerManager

Field Summary
 
Fields inherited from interface commonj.timers.TimerManager
IMMEDIATE, INDEFINITE
 
Constructor Summary
FooTimerManager(ThreadPool pool)
          Create a new TimerManager.
 
Method Summary
 boolean isStopped()
          Returns true if all TimerListeners have completed following stop.
 boolean isStopping()
          Returns true if this TimerManager is stopping or has been stopped.
 boolean isSuspended()
          Returns true if this TimerManager is in the process of or has completed suspending.
 boolean isSuspending()
          Returns true if this TimerManager is in the process of or has completed suspending.
 void resume()
          Resume the TimerManager.
 void run()
          run method for the timer thread.
 commonj.timers.Timer schedule(commonj.timers.TimerListener listener, java.util.Date time)
          Schedules a OneShotTimer to execute at a specified time.
 commonj.timers.Timer schedule(commonj.timers.TimerListener listener, java.util.Date firstTime, long period)
          Schedules a TimerListener to execute repeatedly using fixed-delay execution after the firstTime elapses.
 commonj.timers.Timer schedule(commonj.timers.TimerListener listener, long delay)
          Schedules a TimerListener to execute once after the specified delay.
 commonj.timers.Timer schedule(commonj.timers.TimerListener listener, long delay, long period)
          Schedules a TimerListener to execute repeatedly using fixed-delay execution after the specified delay.
 commonj.timers.Timer scheduleAtFixedRate(commonj.timers.TimerListener listener, java.util.Date firstTime, long period)
          Schedules a TimerListener to execute repeatedly using fixed-rate execution after the firstTime elapses.
 commonj.timers.Timer scheduleAtFixedRate(commonj.timers.TimerListener listener, long delay, long period)
          Schedules a TimerListener to execute repeatedly using fixed-rate execution after the specified delay.
 void shutdown()
          Stop all timers and shutdown the thread pool.
 void stop()
          Destroy the TimerManager.
 void suspend()
          Suspend the TimerManager.
 boolean waitForStop(long timeoutMs)
          Blocks until all TimerListeners have completed execution after a stop request, or the timeout occurs, or the current thread is interrupted, whichever happens first.
 boolean waitForSuspend(long timeoutMs)
          Blocks until all TimerListeners have completed execution after a suspend request, or the timeout occurs, or the current thread is interrupted, whichever happens first.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FooTimerManager

public FooTimerManager(ThreadPool pool)
Create a new TimerManager.

Parameters:
pool - thread pool to execute timers in
Method Detail

shutdown

public void shutdown()
Stop all timers and shutdown the thread pool.


run

public void run()
run method for the timer thread.

Specified by:
run in interface java.lang.Runnable
See Also:
Runnable.run()

isStopped

public boolean isStopped()
Returns true if all TimerListeners have completed following stop.

Specified by:
isStopped in interface commonj.timers.TimerManager
Returns:
true if all TimerListeners have completed following stop
See Also:
TimerManager.isStopped()

isStopping

public boolean isStopping()
Returns true if this TimerManager is stopping or has been stopped.

Specified by:
isStopping in interface commonj.timers.TimerManager
Returns:
true if this TimerManager is stopping or has been stopped
See Also:
TimerManager.isStopping()

isSuspended

public boolean isSuspended()
                    throws java.lang.IllegalStateException
Returns true if this TimerManager is in the process of or has completed suspending.

Specified by:
isSuspended in interface commonj.timers.TimerManager
Returns:
true if this TimerManager has been suspended
Throws:
java.lang.IllegalStateException - if this TimerManager has been stopped.
See Also:
TimerManager.isSuspended()

isSuspending

public boolean isSuspending()
                     throws java.lang.IllegalStateException
Returns true if this TimerManager is in the process of or has completed suspending.

Specified by:
isSuspending in interface commonj.timers.TimerManager
Returns:
true if this TimerManager has been suspended
Throws:
java.lang.IllegalStateException - if this TimerManager has been stopped.
See Also:
TimerManager.isSuspending()

resume

public void resume()
            throws java.lang.IllegalStateException
Resume the TimerManager. All scheduled timers that have expired while suspended will execute immediately. All fixed-rate timers will execute one time, and then again at the next scheduled fixed-rate time.

Specified by:
resume in interface commonj.timers.TimerManager
Throws:
java.lang.IllegalStateException - if this TimerManager has been stopped.
See Also:
TimerManager.resume()

schedule

public commonj.timers.Timer schedule(commonj.timers.TimerListener listener,
                                     java.util.Date time)
                              throws java.lang.IllegalArgumentException,
                                     java.lang.IllegalStateException
Schedules a OneShotTimer to execute at a specified time. If the time is in the past, the TimerListener will execute immediately.

Specified by:
schedule in interface commonj.timers.TimerManager
Parameters:
listener - the TimerListener implementation to invoke when the timer expires.
time - the time at which the timer will expire.
Returns:
the resulting Timer object.
Throws:
java.lang.IllegalArgumentException - thrown when the listener or firstTime is null
java.lang.IllegalStateException - thrown when the TimerManager has been stopped.
See Also:
TimerManager.schedule(commonj.timers.TimerListener, java.util.Date), OneShotTimer

schedule

public commonj.timers.Timer schedule(commonj.timers.TimerListener listener,
                                     long delay)
                              throws java.lang.IllegalArgumentException,
                                     java.lang.IllegalStateException
Schedules a TimerListener to execute once after the specified delay.

Specified by:
schedule in interface commonj.timers.TimerManager
Parameters:
listener - the TimerListener implementation to invoke when the Timer expires.
delay - the number of milliseconds to wait before the Timer expires.
Returns:
the resulting Timer object.
Throws:
java.lang.IllegalArgumentException - thrown when the listener is null or the delay is negative.
java.lang.IllegalStateException - thrown when the TimerManager has been stopped.
See Also:
TimerManager.schedule(commonj.timers.TimerListener, long)

schedule

public commonj.timers.Timer schedule(commonj.timers.TimerListener listener,
                                     java.util.Date firstTime,
                                     long period)
                              throws java.lang.IllegalArgumentException,
                                     java.lang.IllegalStateException
Schedules a TimerListener to execute repeatedly using fixed-delay execution after the firstTime elapses.

TimerListeners are executed at a constant delay based on the actual execution time. Each subsequent execution time is based off of the period and the end time of the previous execution. The period is the delay in between TimerListener executions.

Specified by:
schedule in interface commonj.timers.TimerManager
Parameters:
listener - the TimerListener implementation to invoke when the Timer expires.
firstTime - the time at which the first TimerListener will execute.
period - the number of milliseconds between repeating expiration intervals.
Returns:
the resulting Timer object.
Throws:
java.lang.IllegalArgumentException - thrown when the listener or firstTime is null or the period is negative.
java.lang.IllegalStateException - thrown when the TimerManager has been stopped.
See Also:
TimerManager.schedule(commonj.timers.TimerListener, java.util.Date, long)

schedule

public commonj.timers.Timer schedule(commonj.timers.TimerListener listener,
                                     long delay,
                                     long period)
                              throws java.lang.IllegalArgumentException,
                                     java.lang.IllegalStateException
Schedules a TimerListener to execute repeatedly using fixed-delay execution after the specified delay.

TimerListeners are executed at a constant delay based on the actual execution time. Each subsequent execution time is based off of the period and the end time of the previous execution. The period is the delay in between TimerListener executions.

Specified by:
schedule in interface commonj.timers.TimerManager
Parameters:
listener - the TimerListener implementation to invoke when the Timer expires.
delay - the number of milliseconds to wait before the first Timer expires.
period - the number of milliseconds between repeating expiration intervals.
Returns:
the resulting Timer object.
Throws:
java.lang.IllegalArgumentException - thrown when the listener is null or the period or delay is negative.
java.lang.IllegalStateException - thrown when the TimerManager has been stopped.
See Also:
TimerManager.schedule(commonj.timers.TimerListener, long, long)

scheduleAtFixedRate

public commonj.timers.Timer scheduleAtFixedRate(commonj.timers.TimerListener listener,
                                                java.util.Date firstTime,
                                                long period)
                                         throws java.lang.IllegalArgumentException,
                                                java.lang.IllegalStateException
Schedules a TimerListener to execute repeatedly using fixed-rate execution after the firstTime elapses.

TimerListeners are executed at a constant rate based on the initial scheduled execution time. Each subsequent execution time is based off of the period and the first execution time. This is appropriate for recurring activities that are sensitive to absolute time, such as ringing a chime every hour on the hour. It is also appropriate for recurring activities where the total time to perform a fixed number of executions is important, such as a countdown timer that ticks once every second for ten seconds.

Specified by:
scheduleAtFixedRate in interface commonj.timers.TimerManager
Parameters:
listener - the TimerListener implementation to invoke when the Timer expires.
firstTime - the time at which the first timer will execute.
period - the number of milliseconds between repeating expiration intervals.
Returns:
the resulting Timer object.
Throws:
java.lang.IllegalArgumentException - thrown when the listener or firstTime is null or the period is negative.
java.lang.IllegalStateException - thrown when the TimerManager has been stopped.
See Also:
TimerManager.scheduleAtFixedRate(commonj.timers.TimerListener, java.util.Date, long)

scheduleAtFixedRate

public commonj.timers.Timer scheduleAtFixedRate(commonj.timers.TimerListener listener,
                                                long delay,
                                                long period)
                                         throws java.lang.IllegalArgumentException,
                                                java.lang.IllegalStateException
Schedules a TimerListener to execute repeatedly using fixed-rate execution after the specified delay.

TimerListeners are executed at a constant rate based on the initial scheduled execution time. Each subsequent execution time is based off of the period and the first execution time. This is appropriate for recurring activities that are sensitive to absolute time, such as ringing a chime every hour on the hour. It is also appropriate for recurring activities where the total time to perform a fixed number of executions is important, such as a countdown timer that ticks once every second for ten seconds.

Specified by:
scheduleAtFixedRate in interface commonj.timers.TimerManager
Parameters:
listener - the TimerListener implementation to invoke when the Timer expires.
delay - the number of milliseconds to wait before the first Timer expires.
period - the number of milliseconds between repeating expiration intervals.
Returns:
the resulting Timer object.
Throws:
java.lang.IllegalArgumentException - thrown when the listener is null or the period or delay is negative.
java.lang.IllegalStateException - thrown when the TimerManager has been stopped.
See Also:
TimerManager.scheduleAtFixedRate(commonj.timers.TimerListener, long, long)

stop

public void stop()
          throws java.lang.IllegalStateException
Destroy the TimerManager. All Timers are stopped and all currently executing listeners are permitted to complete.

StopTimerListener.stopTimer events will be called serially with any TimerListener.timerExpired methods. They will not execute concurrently. If a TimerListener is executing, the stopTimer method will be called after the timerExpired method has completed.

CancelTimerListener.timerCancel events do not execute as a result of this method.

Once the a timer manager has been stopped, it can never be re-started. Attempts to schedule a TimerListener, and resume or suspend the TimerManager will result in a thrown IllegalStateException.

Specified by:
stop in interface commonj.timers.TimerManager
Throws:
java.lang.IllegalStateException - If this TimerManager was already stopped.
See Also:
TimerManager.stop()

suspend

public void suspend()
Suspend the TimerManager.

Execution of listeners for timers that expire while the TimerManager is suspended is deferred until the TimerManager is resumed.

This method will return immediately. Use the TimerManager.isSuspended() and TimerManager.waitForSuspend(long) methods to determine the state of the suspend.

Specified by:
suspend in interface commonj.timers.TimerManager
Throws:
java.lang.IllegalStateException - if this TimerManager has been stopped.
See Also:
TimerManager.suspend()

waitForStop

public boolean waitForStop(long timeoutMs)
                    throws java.lang.InterruptedException,
                           java.lang.IllegalArgumentException
Blocks until all TimerListeners have completed execution after a stop request, or the timeout occurs, or the current thread is interrupted, whichever happens first.

Specified by:
waitForStop in interface commonj.timers.TimerManager
Parameters:
timeoutMs - the maximum time to wait
Returns:
true if this TimerManager stopped and false if the timeout elapsed before the stop completed
Throws:
java.lang.InterruptedException - if interrupted while waiting
java.lang.IllegalArgumentException - thrown if the timeoutMs is negative.
See Also:
TimerManager.waitForStop(long)

waitForSuspend

public boolean waitForSuspend(long timeoutMs)
                       throws java.lang.InterruptedException,
                              java.lang.IllegalStateException,
                              java.lang.IllegalArgumentException
Blocks until all TimerListeners have completed execution after a suspend request, or the timeout occurs, or the current thread is interrupted, whichever happens first.

Specified by:
waitForSuspend in interface commonj.timers.TimerManager
Parameters:
timeoutMs - the maximum time to wait
Returns:
true if this TimerManager suspended and false if the timeout elapsed before the suspend completed
Throws:
java.lang.InterruptedException - if interrupted while waiting
java.lang.IllegalStateException - if this TimerManager has been stopped.
java.lang.IllegalArgumentException - thrown if the timeoutMs is negative.
See Also:
TimerManager.waitForSuspend(long)