javax.realtime
Class PeriodicTimer

java.lang.Object
  extended by javax.realtime.AsyncEvent
      extended by javax.realtime.Timer
          extended by 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.

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.
 Clock getClock()
          Returns the instance of Clock that the PeriodicTimer interval is associated with at the time of the call, even when the time value of interval is zero and the PeriodicTimer firing behavior is that of a OneShotTimer.
 AbsoluteTime getFireTime()
          Get the time at which this PeriodicTimer is next expected to fire or to skip.
 AbsoluteTime getFireTime(AbsoluteTime dest)
          Get the time at which this PeriodicTimer is next expected to fire or to skip.
 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
addHandler, bindTo, destroy, disable, enable, fire, handledBy, isRunning, removeHandler, reschedule, setHandler, start, start, stop
 
Methods inherited from class javax.realtime.AsyncEvent
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.
IllegalAssignmentError - Thrown if this PeriodicTimer cannot hold references to handler and interval.
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.
IllegalAssignmentError - Thrown if this PeriodicTimer cannot hold references to handler, clock and interval.
java.lang.UnsupportedOperationException - Thrown if the timer functionality cannot be supported using the clock associated with start or the given clock.
Method Detail

getClock

public Clock getClock()
Returns the instance of Clock that the PeriodicTimer interval is associated with at the time of the call, even when the time value of interval is zero and the PeriodicTimer firing behavior is that of a OneShotTimer.

Overrides:
getClock in class Timer
Returns:
The instance of Clock that the interval is associated with at the time of the call.
Throws:
java.lang.IllegalStateException - Thrown if this Timer has been destroyed.
Since:
1.0.1

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.

getFireTime

public AbsoluteTime getFireTime()
Get the time at which this PeriodicTimer is next expected to fire or to skip. If the PeriodicTimer is disabled, the returned time is that of the skipping of the firing. If the PeriodicTimer is not-active it throws IllegalStateException.

Overrides:
getFireTime in class Timer
Returns:
The absolute time at which this is next expected to fire or to skip, in a newly allocated AbsoluteTime object. If the timer has been created or re-scheduled (see Timer.reschedule(HighResolutionTime time)) using an instance of RelativeTime for its time parameter then it will return the sum of the current time and the RelativeTime remaining time before the timer is expected to fire/skip. Within a periodic timer activation, the returned time is associated with the start clock before the first fire (or skip) time, and associated with the interval clock otherwise.
Throws:
java.lang.ArithmeticException - Thrown if the result does not fit in the normalized format.
java.lang.IllegalStateException - Thrown if this Timer has been destroyed, or if it is not-active.

getFireTime

public AbsoluteTime getFireTime(AbsoluteTime dest)
Get the time at which this PeriodicTimer is next expected to fire or to skip. If the PeriodicTimer is disabled, the returned time is that of the skipping of the firing. If the PeriodicTimer is not-active it throws IllegalStateException.

Overrides:
getFireTime in class Timer
Parameters:
dest - The instance of AbsoluteTime which will be updated in place and returned. The clock association of the dest parameter is ignored. When dest is null a new object is allocated for the result.
Returns:
The instance of AbsoluteTime passed as parameter, with time values representing the absolute time at which this is expected to fire or to skip. If the dest parameter is null the result is returned in a newly allocated object. If the timer has been created or re-scheduled (see Timer.reschedule(HighResolutionTime time)) using an instance of RelativeTime for its time parameter then it will return the sum of the current time and the RelativeTime remaining time before the timer is expected to fire/skip. Within a periodic timer activation, the returned time is associated with the start clock before the first fire (or skip) time, and associated with the interval clock otherwise.
Throws:
java.lang.ArithmeticException - Thrown if the result does not fit in the normalized format.
java.lang.IllegalStateException - Thrown if this Timer has been destroyed, or if it is not-active.
Since:
1.0.1

getInterval

public RelativeTime getInterval()
Gets the interval of this Timer.

Returns:
The RelativeTime instance assigned as this periodic timer's interval by the constructor or setInterval(RelativeTime).
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.
IllegalAssignmentError - Thrown if this PeriodicTimer cannot hold a reference to interval.
java.lang.IllegalStateException - Thrown if this Timer has been destroyed.