javatools.cron
Class Cron

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--javatools.cron.Cron

All Implemented Interfaces:

java.lang.Runnable, Server

public class Cron

extends java.lang.Thread

implements Server

Cron is a class that schedules events according to a known algorithm. Most usually, this algorithm will be the Unix Crontab algorithm which can schedule tasks for certain hours, days and months etc. But you can just as well write your own CrontabEntry class that, say, scheduled according to the phases of the moon, or the movement of the planets, or any other deterministic algorithm you care to name. Or you could also mix and match the supplied unix crontab algorithms with your own custom ones. In summary, cron executes a set of crontabEntries that conform to the CrontabEntryInterface interface. This interface only knows two things: when is the next event going to happen after a certain time, and secondly, what to do when that event happens.

Neither does Cron have any knowledge of what exactly is to be done when the event occurs. It could be starting a thread, or executing a process or doing anything else at all. That is totally up to the CrontabEntry class. The algorithm that Cron uses is as follows... We keep a schedule of "soon to occur" events. Soon to occur is defined as the next event to occur for each timetable entry plus all the events that will occur between now and now plus the futureScheduleInterval. FutureScheduleInterval is by default 5 minutes.

We need to schedule at least one event for each timetable entry to make sure that we will awaken at the correct time. But scheduling only one event for each timetable may not be enough for times of heavy system load. We could schedule all events up until the present moment in time but we choose to schedule a bit into the future too to be ahead of the game. The optimum amount for this value probably needs some experimentation and probably depends on the system load. But I anticipate that the default futureScheduleInterval should be fine for 99.99% of cases.

We store some extra information about each CrontabEntry in the timetable in the private class CronEntry. In particular we need to remember for each CrontabEntry up until what point in time we have scheduled (so that we don't schedule the same event twice), and also how many events we have scheduled for this entry (so that we don't schedule any more than one event for each entry that is further in the future than the futureScheduleInterval).

Your application may consider the Cron process to be of higher priority in scheduling. If so, feel free to increase the priority of the Cron thread using the base class Thread methods.

Nested Class Summary

(package private) class	Cron.CronConfig Why do we make a separate class out of these two variables? It allows us to replace both atomically without resorting to using synchronized.
(package private) class	Cron.CronEntry A private class that we use to keep track of all the timetable entries we have.
class	Cron.CronEvent When we wish to schedule a particular event to happen, we create an object of this type and add it to the schedule.

Field Summary

(package private) Cron.CronConfig	currentConfig
(package private) long	futureScheduleInterval How far in the future will we schedule events for?
(package private) boolean	keepGoing Whether Cron has been asked to shutdown or not.
static int	SMALLEST_INTERVAL The smallest interval of time that we contemplate in milliseconds.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Cron()
Default constructor.

Cron(java.util.Collection crontabEntries)

Method Summary

long	getFutureScheduleInterval() Discover the Future Scheduling Interval
void	logTime(long time) A debugging function.
protected java.util.List	makeCronEntries(java.util.Collection crontabEntries)
void	run() Run the Cron process.
long	runEvents(Cron.CronConfig conf, long now) Run all the events that occur before or equal to now.
void	scheduleEvent(Cron.CronConfig conf, long time, Cron.CronEntry entry) Schedule an event to occur at a certain time for a certain crontab entry.
void	scheduleEvents(Cron.CronConfig conf, long now) Discover all the "soon to occur" events.
void	setCrontab(java.util.Collection crontabEntries) Reset cron's crontab schedule.
void	setFutureScheduleInterval(long time) Set the Future Scheduling Interval
void	shutdown() Shutdown the cron thread.
java.lang.String	toString()

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, yield

Methods inherited from class java.lang.Object

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

Field Detail

SMALLEST_INTERVAL

public static final int SMALLEST_INTERVAL

The smallest interval of time that we contemplate in milliseconds.

See Also:

Constant Field Values

currentConfig

Cron.CronConfig currentConfig

futureScheduleInterval

long futureScheduleInterval

How far in the future will we schedule events for?

keepGoing

boolean keepGoing

Whether Cron has been asked to shutdown or not.

Constructor Detail

Cron

public Cron(java.util.Collection crontabEntries)

Parameters:

crontabEntries - a collection of

See Also:

objects.

Cron

public Cron()

Default constructor. Pretty useless without doing a setCrontab().

Method Detail

setCrontab

public void setCrontab(java.util.Collection crontabEntries)

Reset cron's crontab schedule. This is callable asynchronously at any time. We go to some trouble to allow this to happen. Firstly, we use the ThreadSleeper to ensure Cron wakes up to schedule the new crontab, no matter at what stage of execution cron is in. Secondly, we use the CronConfig class to ensure that we reset the schedule and the cronEntries atomically without use of synchronized. Then in the run() method we take a copy of the config variable just in case it changes at a random time.

Parameters:

crontabEntries - a collection of CrontabEntryInterface objects.

setFutureScheduleInterval

public void setFutureScheduleInterval(long time)

Set the Future Scheduling Interval

Parameters:

time - The new futureScheduleInterval value

getFutureScheduleInterval

public long getFutureScheduleInterval()

Discover the Future Scheduling Interval

Returns:

The futureScheduleInterval value

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Thread

shutdown

public void shutdown()

Shutdown the cron thread.

Specified by:

shutdown in interface Server

run

public void run()

Run the Cron process.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

runEvents

public long runEvents(Cron.CronConfig conf,
                      long now)

Run all the events that occur before or equal to now.

Parameters:

conf - Description of Parameter

now - Description of Parameter

Returns:

The next event time that has not yet been executed.

logTime

public void logTime(long time)

A debugging function.

Parameters:

time - Description of Parameter

scheduleEvent

public void scheduleEvent(Cron.CronConfig conf,
                          long time,
                          Cron.CronEntry entry)

Schedule an event to occur at a certain time for a certain crontab entry.

Parameters:

time - The time the event should occur

entry - The crontab entry event that should occur.

conf - Description of Parameter

scheduleEvents

public void scheduleEvents(Cron.CronConfig conf,
                           long now)

Discover all the "soon to occur" events.

Parameters:

conf - Description of Parameter

now - Description of Parameter

makeCronEntries

protected java.util.List makeCronEntries(java.util.Collection crontabEntries)

Parameters:

crontabEntries - a collection of CrontabEntryInterface objects.

Returns:

Description of the Returned Value