org.javades.jsimulation.r5

Class AbstractSimTimer

java.lang.Object

org.javades.jsimulation.r5.AbstractSimTimer

public abstract class AbstractSimTimer
extends Object

A general-purpose timer.

This abstract timer class hides the details of scheduling a SimEvent with an appropriate SimEventAction on a SimEventList and instead uses a callback method expireAction(double) to notify concrete subclasses of timer expiration. Concrete subclasses only have to override expireAction(double).

The timer is scheduled on a SimEventList through schedule(double, org.javades.jsimulation.r5.SimEventList), passing the (positive or zero) delay. Upon scheduling, the override-able scheduleAction(double) is invoked (the default implementation does nothing).

Canceling a pending timer event is supported through cancel(). Canceling a timer that is not currently scheduled has no effect. Upon cancellation, the override-able cancelAction(double) is invoked (the default implementation does nothing).

A timer can only be scheduled on a single SimEventList at a time, but once expired or canceled, the timer can be rescheduled, even on a different SimEventList. An attempt to schedule an already scheduled timer will result in a RuntimeException.

Although (believed to be) still functional, this class is maintained for mainly historic reasons, since its functionality can be much easier obtained by scheduling a SimEventAction on a SimEventList.

Last javadoc Review: Jan de Jongh, TNO, 20180404, r5.1.0.

Constructor Summary

Constructors

Constructor and Description
AbstractSimTimer() Creates a timer without name (null name).
AbstractSimTimer(String name) Creates a timer with given name.

Method Summary

Modifier and Type	Method and Description
void	cancel() Cancels a pending timer.
void	cancelAction(double time) Method that is invoked upon canceling the timer.
abstract void	expireAction(double time) Abstract method that is invoked upon expiration of the timer.
String	getName() Returns the name of this timer.
void	schedule(double delay, SimEventList eventList) Schedules this timer on an event list.
void	scheduleAction(double time) Method that is invoked upon scheduling the timer.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractSimTimer

public AbstractSimTimer(String name)

Creates a timer with given name.

Parameters:

name - The name of the timer; replaced with the empty string when null.

AbstractSimTimer

public AbstractSimTimer()

Creates a timer without name (null name).

The name is replaced with the empty string.

Method Detail

getName

public final String getName()

Returns the name of this timer.

Returns:

The name of this timer; non-null but may be empty.

expireAction

public abstract void expireAction(double time)

Abstract method that is invoked upon expiration of the timer.

Parameters:

time - The current time at expiration.

scheduleAction

public void scheduleAction(double time)

Method that is invoked upon scheduling the timer.

The default implementation does nothing.

Parameters:

time - The current time when scheduling.

See Also:

schedule(double, org.javades.jsimulation.r5.SimEventList)

cancelAction

public void cancelAction(double time)

Method that is invoked upon canceling the timer.

The default implementation does nothing.

Note that this method is only invoked if the timer was actually scheduled on a SimEventList when cancel() was invoked.

Parameters:

time - The current time when canceling.

schedule

public void schedule(double delay,
                     SimEventList eventList)

Schedules this timer on an event list. Invokes scheduleAction(double) once the appropriate event is scheduled on the event lList.

Note that this method take the current time from the event list to which it adds a delay in order to schedule the expiration event. Especially in between event-list runs, the current time may be Double.NEGATIVE_INFINITY, leading to indefinite rescheduling of the times at negative infinite.

Parameters:

delay - The delay until expiration.

eventList - The event list.

Throws:

IllegalArgumentException - If delay is negative or infinite (positive or negative), the eventList is null, or the current time on the event list is negative or positive infinity.

RuntimeException - If the timer is already scheduled.

cancel

public void cancel()

Cancels a pending timer.

Ignored if this timer is not scheduled. Invokes cancelAction(double) after removal of the appropriate event on the event list (and not if the timer was previously unscheduled).

See Also:

cancelAction(double)