javax.realtime

Class Timer

java.lang.Object

javax.realtime.AsyncBaseEvent

javax.realtime.AsyncEvent

javax.realtime.Timer

All Implemented Interfaces:

ActiveEvent<Timer,TimeDispatcher>, Releasable<Timer,TimeDispatcher>

Direct Known Subclasses:

OneShotTimer, PeriodicTimer

public abstract class Timer
extends AsyncEvent
implements ActiveEvent<Timer,TimeDispatcher>

Jamaica Real-Time Specification for Java class Timer.

abstract super class of PeriodicTimer or OneShotTimer. These timers are asynchronous events that fire at a given time.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Timer(HighResolutionTime<?> time, AsyncEventHandler handler, TimeDispatcher dispatcher) Creates a timer that fires according to the given time based on the Clock associated with time and is dispatched by the specified dispatcher.
protected	Timer(HighResolutionTime<?> time, Clock clock, AsyncEventHandler handler) Constructor to create a timer with the given time, clock and handler.

Method Summary

Modifier and Type	Method and Description
void	bindTo(java.lang.String happening) Should not be called, since this was only meant for binding happenings to normal instances AsyncEvent, not to special subclasses.
ReleaseParameters<?>	createReleaseParameters() createReleaseParameters creates the default release parameters for this event.
void	destroy() destroy destroys this timer, i.e., stops it from counting.
protected void	finalize()
void	fire() fires this event unless firing is disabled and reschedules the timer in case it is periodic.
Clock	getClock() getClock returns the clock this timer was based on.
TimeDispatcher	getDispatcher() Obtain the current dispatcher for this event.
AbsoluteTime	getEffectiveStartTime() Returns a newly-created time representing the time when the timer actually started, or when the timer has been rescheduled, the effective start time after the reschedule.
AbsoluteTime	getEffectiveStartTime(AbsoluteTime dest) Updates dest to represent the time when the timer actually started, or when the timer has been rescheduled, the effective start time after the reschedule.
AbsoluteTime	getFireTime() getFireTime returns the time at which this timer is expected to fire or skip firing (because it is disabled) next.
AbsoluteTime	getFireTime(AbsoluteTime dest) getFireTime returns the time at which this timer is expected to fire or skip firing (because it is disabled) next.
HighResolutionTime<?>	getStart() Gets the start time of this Timer.
boolean	isActive() Determines the activation state of this event, i.e., it has been started but not yet stopped again.
boolean	isRunning() isRunning returns true if this timer has been started (it is active) and it has not been disabled.
void	reschedule(HighResolutionTime<?> time) reschedule changes the time for this event.
TimeDispatcher	setDispatcher(TimeDispatcher dispatcher) Change the current dispatcher for this event.
protected void	setStartTime(HighResolutionTime<?> time) Sets the time when this timer should fire.
void	start() start this timer, i.e., make it active and enabled
void	start(boolean disabled) start this timer, i.e., make it active.
void	start(boolean disabled, PhasingPolicy phasingPolicy) Starts the timer with the specified PhasingPolicy and the specified disabled state.
void	start(PhasingPolicy phasingPolicy) Starts the timer with the specified PhasingPolicy.
boolean	stop() stop stops this active timer changing its state to not-active and disabled.

Methods inherited from class javax.realtime.AsyncEvent

addHandler, handledBy, removeHandler, setHandler, unbindTo

Methods inherited from class javax.realtime.AsyncBaseEvent

addHandler, disable, enable, handledBy, hasHandlers, removeHandler, setHandler

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.realtime.ActiveEvent

disable, enable

Constructor Detail

Timer

protected Timer(HighResolutionTime<?> time,
                Clock clock,
                AsyncEventHandler handler)

Constructor to create a timer with the given time, clock and handler.

Parameters:

time - The time when this timer should fire. May be null, in this case this is equal to new RelativeTime(0, 0) and the firing will occur immediately after a call to start().

clock - the clock this timer should be based upon. May be null to use the default System.getRealtimeClock().

handler - The handler that will be released when this timer fires. May be null to have no handler until one will be added via addHandler.

Throws:

StaticIllegalArgumentException - if time is a negative RelativeTime.

Timer

protected Timer(HighResolutionTime<?> time,
                AsyncEventHandler handler,
                TimeDispatcher dispatcher)

Creates a timer that fires according to the given time based on the Clock associated with time and is dispatched by the specified dispatcher.

Parameters:

time - The parameter used to determine when to fire the event. A time value of null is equivalent to a RelativeTime of 0, and in this case the Timer fires immediately upon a call to start().

handler - The default handler to use for this event. When null, no handler is associated with the timer and nothing will happen when this event fires unless a handler is subsequently associated with the timer using the addHandler() or setHandler() method.

dispatcher - The object used to interface between this timer and its associated clock. When null, the system default dispatcher is used.

Throws:

StaticIllegalArgumentException - when time is a negative RelativeTime value.

StaticUnsupportedOperationException - when time has a Chronograph is not a clock.

IllegalAssignmentError - when this Timer cannot hold references to handler and clock.

Since:

RTSJ 2.0

Method Detail

getDispatcher

public TimeDispatcher getDispatcher()

Obtain the current dispatcher for this event.

Specified by:

getDispatcher in interface ActiveEvent<Timer,TimeDispatcher>

Specified by:

getDispatcher in interface Releasable<Timer,TimeDispatcher>

Returns:

the dispatcher associated with this event.

Throws:

java.lang.UnsupportedOperationException - always, since it is not yet implemented.

setDispatcher

public TimeDispatcher setDispatcher(TimeDispatcher dispatcher)

Change the current dispatcher for this event. When dispatcher is null, the default dispatcher is restored.

Specified by:

setDispatcher in interface ActiveEvent<Timer,TimeDispatcher>

Returns:

the dispatcher associated with this event.

Throws:

java.lang.UnsupportedOperationException - always, since it is not yet implemented.

isRunning

public boolean isRunning()

isRunning returns true if this timer has been started (it is active) and it has not been disabled.

Specified by:

isRunning in interface ActiveEvent<Timer,TimeDispatcher>

Overrides:

isRunning in class AsyncBaseEvent

Returns:

true if this timer expects to fire.

isActive

public boolean isActive()

Description copied from interface: ActiveEvent

Determines the activation state of this event, i.e., it has been started but not yet stopped again.

Specified by:

isActive in interface ActiveEvent<Timer,TimeDispatcher>

Returns:

true when active, false otherwise.

start

public void start()

start this timer, i.e., make it active and enabled

Specified by:

start in interface ActiveEvent<Timer,TimeDispatcher>

start

public void start(boolean disabled)

start this timer, i.e., make it active.

Specified by:

start in interface ActiveEvent<Timer,TimeDispatcher>

Parameters:

disabled - true to make this timer active but disabled.

Throws:

StaticIllegalStateException - if this timer is destroyed.

start

public void start(PhasingPolicy phasingPolicy)
           throws LateStartException,
                  StaticIllegalArgumentException

Starts the timer with the specified PhasingPolicy.

Parameters:

phasingPolicy - Determines what happens when the start is too late.

Throws:

LateStartException - when this method is called after its absolute start time and the phasingPolicy is PhasingPolicy.STRICT_PHASING.

StaticIllegalArgumentException - when the start time of this timer is not an absolute time, or phasingPolicy is null or, when this in not a periodic timer, ADJUST_FORWARD or ADJUST_BACKWARD.

Since:

RTSJ 2.0

start

public void start(boolean disabled,
                  PhasingPolicy phasingPolicy)
           throws LateStartException,
                  StaticIllegalArgumentException

Starts the timer with the specified PhasingPolicy and the specified disabled state.

Parameters:

disabled - It determines the mode of start: true for enabled and false for disabled for consistency with start(boolean).

phasingPolicy - It determines what happens when the start is too late.

Throws:

LateStartException - when this method is called after its absolute start time and the phasingPolicy is PhasingPolicy.STRICT_PHASING.

StaticIllegalArgumentException - when the start time of this timer is not an absolute time, or phasingPolicy is null or, when this in not a periodic timer, ADJUST_FORWARD or ADJUST_BACKWARD.

Since:

RTSJ 2.0

stop

public boolean stop()

stop stops this active timer changing its state to not-active and disabled.

Specified by:

stop in interface ActiveEvent<Timer,TimeDispatcher>

Returns:

true if this timer was active before the call, false if it was not.

Throws:

StaticIllegalStateException - if this timer is destroyed.

createReleaseParameters

public ReleaseParameters<?> createReleaseParameters()

createReleaseParameters creates the default release parameters for this event. The default implementation creates AperiodicParemters without cost/ deadline and without overrun or miss handler.

Overrides:

createReleaseParameters in class AsyncEvent

Returns:

An instance of ReleaseParameters appropriate for handlers for this event.

Throws:

StaticIllegalStateException - if this timer is destroyed.

destroy

public void destroy()

destroy destroys this timer, i.e., stops it from counting. This will release important resources that were allocated for this timer, it may free a thread that was generated for this counter.

Throws:

StaticIllegalStateException - if this timer has been destroyed.

getClock

public Clock getClock()

getClock returns the clock this timer was based on.

Returns:

the clock of this timer.

Throws:

StaticIllegalStateException - if this timer has been destroyed.

getStart

public HighResolutionTime<?> getStart()

Gets the start time of this Timer. Note that the start time uses copy semantics, so changes made to the value returned by this method do not affect the start time of this Timer.

Returns:

a reference to the time (or start) parameter used when constructing this Timer, ensuring the content has the original values.

Since:

RTSJ 2.0

getEffectiveStartTime

public AbsoluteTime getEffectiveStartTime()
                                   throws StaticIllegalStateException,
                                          java.lang.ArithmeticException

Returns a newly-created time representing the time when the timer actually started, or when the timer has been rescheduled, the effective start time after the reschedule.

Returns:

the time this actually started.

Throws:

StaticIllegalStateException - when the timer is not active or has been destroyed.

java.lang.ArithmeticException - when the result does not fit in the normalized format.

Since:

RTSJ 2.0

getEffectiveStartTime

public AbsoluteTime getEffectiveStartTime(AbsoluteTime dest)
                                   throws StaticIllegalStateException,
                                          java.lang.ArithmeticException

Updates dest to represent the time when the timer actually started, or when the timer has been rescheduled, the effective start time after the reschedule. When dest is null, behaves as if getEffectiveStartTime() had been called.

Parameters:

dest - An object used to store the time this actually started.

Returns:

the time when the timer actually started, or when it has been rescheduled, the effective start time after the reschedule.

Throws:

StaticIllegalStateException - when the timer is not active or has been destroyed.

java.lang.ArithmeticException - when the result does not fit in the normalized format.

Since:

RTSJ 2.0

getFireTime

public AbsoluteTime getFireTime()

getFireTime returns the time at which this timer is expected to fire or skip firing (because it is disabled) next.

Returns:

a new instance of AbsoluteTime that holds the next firing time.

Throws:

StaticIllegalStateException - if this timer has been destroyed or it is not active.

getFireTime

public AbsoluteTime getFireTime(AbsoluteTime dest)

getFireTime returns the time at which this timer is expected to fire or skip firing (because it is disabled) next.

Parameters:

dest - the AbsoluteTime which will be updated and returned if not null. If dest is null, a new instance of AbsoluteTime will be returned.

Returns:

the updated given AbsoluteTime or a new instance that holds the next firing time.

Throws:

StaticIllegalStateException - if this timer has been destroyed or it is not active.

reschedule

public void reschedule(HighResolutionTime<?> time)

reschedule changes the time for this event. This changes the first time a timer fires.

Parameters:

time - the new time parameter.

Throws:

StaticIllegalStateException - if this timer has been destroyed.

fire

public void fire()

fires this event unless firing is disabled and reschedules the timer in case it is periodic.

Overrides:

fire in class AsyncEvent

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class AsyncBaseEvent

Throws:

java.lang.Throwable

bindTo

public void bindTo(java.lang.String happening)
            throws java.lang.UnsupportedOperationException

Should not be called, since this was only meant for binding happenings to normal instances AsyncEvent, not to special subclasses.

Overrides:

bindTo in class AsyncEvent

Parameters:

happening - to which to bind.

Throws:

java.lang.UnsupportedOperationException - everytime, since this operation is not supported.

setStartTime

protected void setStartTime(HighResolutionTime<?> time)

Sets the time when this timer should fire.

Parameters:

time - The time when this timer should fire, may be null, in this case this is equal to new RelativeTime(0, 0) and the firing will occur immediately after a call to start().