javax.realtime
Class PeriodicTimer

java.lang.Object
  javax.realtime.AsyncEvent
      javax.realtime.Timer
          javax.realtime.PeriodicTimer

public class PeriodicTimer
extends Timer

An AsyncEvent whose fire method is executed periodically according to the given parameters. The beginning of the first period is set or measured using the clock associated with the Timer start time. The calculation of the period uses the clock associated with the Timer interval, unless a Clock is given, in which case the calculation of the period uses that clock.
The first firing is at the beginning of the first interval.
If an interval greater than 0 is given, the timer will fire periodically. If an interval of 0 is given, the PeriodicTimer will only fire once, unless restarted after expiration, behaving like a OneShotTimer. In all cases, if the timer is disabled when the firing time is reached, that particular firing is lost (skipped). If enabled at a later time, it will fire at its next scheduled time.
If the clock time has already passed the beginning of the first period, the PeriodicTimer will fire immediately after it is started.
If one of the HighResolutionTime argument types is RationalTime (now deprecated) then the system guarantees that the fire method will be executed exactly frequency times every unit time (see RationalTime constructors) by adjusting the interval between executions of fire(). This is similar to a thread with PeriodicParameters except that it is lighter weight.
Semantics details are described in the Timer pseudo-code and compact graphic representation of state transitions.

Caution: This class is explicitly unsafe in multithreaded situations when it is being changed. No synchronization is done. It is assumed that users of this class who are mutating instances will be doing their own synchronization at a higher level.

Field Summary

Fields inherited from class javax.realtime.Timer

_time

Constructor Summary

PeriodicTimer(HighResolutionTime start, RelativeTime interval, AsyncEventHandler handler)
Create an instance of PeriodicTimer that executes its fire method periodically.

PeriodicTimer(HighResolutionTime start, RelativeTime interval, Clock clock, AsyncEventHandler handler)
Create an instance of PeriodicTimer that executes its fire method periodically.

Method Summary

ReleaseParameters	createReleaseParameters() Create a release parameters object with new objects containing copies of the values corresponding to this timer.
RelativeTime	getInterval() Gets the interval of this Timer.
void	setInterval(RelativeTime interval) Reset the interval value of this.

Methods inherited from class javax.realtime.Timer

bindTo, destroy, disable, enable, fire, getClock, getFireTime, getFireTime, isRunning, reschedule, start, start, stop

Methods inherited from class javax.realtime.AsyncEvent

addHandler, handledBy, removeHandler, setHandler, unbindTo

Methods inherited from class java.lang.Object

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

Constructor Detail

PeriodicTimer

public PeriodicTimer(HighResolutionTime start,
                     RelativeTime interval,
                     AsyncEventHandler handler)

Create an instance of PeriodicTimer that executes its fire method periodically.

Parameters:

start - The time that specifies when the first interval begins, based on the clock associated with it. A start value of null is equivalent to a RelativeTime of 0, and in this case the Timer fires immediately upon a call to start().

interval - The period of the timer. Its usage is based on the clock associated with it. If interval is zero or null, the period is ignored and the firing behavior of the PeriodicTimer is that of a OneShotTimer.

handler - The AsyncEventHandler that will be released when the timer fires. If null, no handler is associated with this Timer and nothing will happen when this event fires unless a handler is subsequently associated with the timer using the addHandler() or setHandler() method.

Throws:

java.lang.IllegalArgumentException - Thrown if start or interval is a RelativeTime instance with a value less than zero. java.lang.UnsupportedOperationException - Thrown if the timer functionality cannot be supported using the clock associated with start or the clock associated with interval.

PeriodicTimer

public PeriodicTimer(HighResolutionTime start,
                     RelativeTime interval,
                     Clock clock,
                     AsyncEventHandler handler)

Create an instance of PeriodicTimer that executes its fire method periodically.

Parameters:

start - The time that specifies when the first interval begins, based on the clock associated with it. A start value of null is equivalent to a RelativeTime of 0, and in this case the Timer fires immediately upon a call to start().

interval - The period of the timer. Its usage is based on the clock specified by the clock parameter. If interval is zero or null, the period is ignored and the firing behavior of the PeriodicTimer is that of a OneShotTimer.

clock - The clock to be used to time the interval. If null, the system Realtime clock is used. The Clock association of the parameter interval is always ignored.

handler - The AsyncEventHandler that will be released when fire is invoked. If null, no handler is associated with this Timer and nothing will happen when this event fires unless a handler is subsequently associated with the timer using the addHandler() or setHandler() method.

Throws:

java.lang.IllegalArgumentException - Thrown if start or interval is a RelativeTime instance with a value less than zero.

java.lang.UnsupportedOperationException - Thrown if the timer functionality cannot be supported using the clock associated with start or the given clock.

Method Detail

createReleaseParameters

public ReleaseParameters createReleaseParameters()

Create a release parameters object with new objects containing copies of the values corresponding to this timer. When the PeriodicTimer interval is greater than 0, create a PeriodicParameters object with a start time and period that correspond to the next firing (or skipping) time, and interval, of this timer. When the interval is 0, create an AperiodicParameters object, since in this case the timer behaves like a OneShotTimer.

If this timer is active, then the start time is the next firing (or skipping) time returned as an AbsoluteTime. Otherwise, the start time is the initial firing (or skipping) time, as set by the last call to reschedule, or if there was no such call, by the constructor of this timer.

Overrides:

createReleaseParameters in class Timer

Returns:

A new release parameters object with new objects containing copies of the values corresponding to this timer. If the interval is greater than zero, return a new instance of PeriodicParameters. If the interval is zero return a new instance of AperiodicParameters.

Throws:

java.lang.IllegalStateException - Thrown if this Timer has been destroyed.

getInterval

public RelativeTime getInterval()

Gets the interval of this Timer.

Returns:

The RelativeTime instance with the value of this timer's interval.

Throws:

java.lang.IllegalStateException - Thrown if this Timer has been destroyed.

setInterval

public void setInterval(RelativeTime interval)

Reset the interval value of this.

Parameters:

interval - A RelativeTime object which is the interval used to reset this Timer. A null interval is interpreted as RelativeTime (0,0).

The interval does not affect the first firing (or skipping) of a timer's activation. At each firing (or skipping), the next fire (or skip) time of an active periodic timer is established based on the interval currently in use. Resetting the interval of an active periodic timer only effects future fire (or skip) times after the next.

Throws:

java.lang.IllegalArgumentException - Thrown if interval is a RelativeTime instance with a value less than zero.

java.lang.IllegalStateException - Thrown if this Timer has been destroyed.