commonj.timers

Interface Timer

public interface Timer

A Timer is returned when a TimerListener is scheduled using one of the TimerManager.schedule methods. It allows retrieving information about the scheduled TimerListener and allows cancelling it.

Timers are transient and not transactional and run inside the JVM which created them. If a cluster-wide scheduled event is required or it needs to be persistent, transactional or recoverable then a service such as the EJB 2.1 Timer service should be used instead.

See Also:

Timer, TimerListener

Method Summary

Modifier and Type	Method and Description
boolean	cancel() This cancels the timer and all future TimerListener invocations and may be called during the TimerListener.timerExpired method.
long	getPeriod() Return the period used to compute the time this timer will repeat.
long	getScheduledExecutionTime() Returns the next absolute scheduled execution time in milliseconds.
TimerListener	getTimerListener() Returns the application-supplied TimerListener associated with this Timer.

Method Detail

cancel

boolean cancel()

This cancels the timer and all future TimerListener invocations and may be called during the TimerListener.timerExpired method.

CancelTimerListener.timerCancel events may be called concurrently with any TimerListener.timerExpired methods. Proper thread synchronization techiniques must be employed to ensure consistency. Once a Timer is cancelled an application must not use the Timer instance again.

Returns:

true if this prevented the next execution of this timer. False if this was already cancelled or had already expired in the one shot case.

See Also:

CancelTimerListener

getTimerListener

TimerListener getTimerListener()

Returns the application-supplied TimerListener associated with this Timer.

Returns:

The TimerListener associated with the timer.

Throws:

IllegalStateException - if the TimerManager has been stopped.

getScheduledExecutionTime

long getScheduledExecutionTime()
                        throws IllegalStateException

Returns the next absolute scheduled execution time in milliseconds.

If invoked while a TimerListener is running, the return value is the scheduled execution time of the current TimerListener execution.

This method is typically invoked from within a TimerListener's timerExpired method, to determine whether the current execution of the task is sufficiently timely to warrant performing the scheduled activity:

    public void timerExpired(Timer t) {
        if (System.currentTimeMillis() - t.scheduledExecutionTime() >=
            MAX_TARDINESS)
                return;  // Too late; skip this execution.
        // Perform the task
    }
  

If the timer has been suspended, the time reflects the most recently-calculated execution time prior to being suspended.

Returns:

the time in milliseconds at which the TimerListener is scheduled to run next.

Throws:

IllegalStateException - if the TimerManager has been stopped.

getPeriod

long getPeriod()

Return the period used to compute the time this timer will repeat. A value of zero indicates that the timer is non-repeating.

Returns:

the period in milliseconds between timer executions.