it.sauronsoftware.cron4j
Class Scheduler

java.lang.Object
  extended by it.sauronsoftware.cron4j.Scheduler

public class Scheduler
extends java.lang.Object

The cron4j scheduler.

With a Scheduler instance you can schedule as many tasks as you need, whose execution is regulated by UNIX crontab-like patterns.

First of all you have to instance a Scheduler object:

 Scheduler myScheduler = new Scheduler();
 

Now schedule your tasks, given as plain Runnable objects:

 myScheduler.scheduler(aRunnableObject, aUNIXCrontabLikeSchedulingPattern);
 

Start the scheduler:

 myScheduler.start();
 

Stop the scheduler when you need it no more:

 myScheduler.stop();
 

In every moment of the scheduler life you can schedule another task calling its schedule() method, regardless it is started or not. All you need, once again, is a Runnable object and a scheduling pattern.

Note that the schedule() method gives you back an identifier for the task. With its identifier you can retrieve later informations about the task, and you can also reschedule() and deschedule() it.

Scheduling patterns

A UNIX crontab-like pattern is a string splitted in five space separated parts. Each part is intented as:

  1. Minutes sub-pattern. During which minutes of the hour should the task been launched? The values range is from 0 to 59.
  2. Hours sub-pattern. During which hours of the day should the task been launched? The values range is from 0 to 23.
  3. Days of month sub-pattern. During which days of the month should the task been launched? The values range is from 0 to 31.
  4. Months sub-pattern. During which months of the year should the task been launched? The values range is from 1 (January) to 12 (December), otherwise this sub-pattern allows the aliases "jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov" and "dec".
  5. Days of week sub-pattern. During which days of the week should the task been launched? The values range is from 0 (Sunday) to 6 (Saturday), otherwise this sub-pattern allows the aliases "sun", "mon", "tue", "wed", "thu", "fri" and "sat".

The star wildcard character is also admitted, indicating "every minute of the hour", "every hour of the day", "every day of the month", "every month of the year" and "every day of the week", according to the sub-pattern in which it is used.

Once the scheduler is started, a task will be launched when the five parts in its scheduling pattern will be true at the same time.

Some examples:

5 * * * *
This pattern causes a task to be launched once every hour, at the begin of the fifth minute (00:05, 01:05, 02:05 etc.).

* * * * *
This pattern causes a task to be launched every minute.

* 12 * * Mon
This pattern causes a task to be launched every minute during the 12th hour of Monday.

* 12 16 * Mon
This pattern causes a task to be launched every minute during the 12th hour of Monday, 16th, but only if the day is the 16th of the month.

Every sub-pattern can contain two or more comma separated values.

59 11 * * 1,2,3,4,5
This pattern causes a task to be launched at 11:59AM on Monday, Tuesday, Wednesday, Thursday and Friday.

Values intervals are admitted and defined using the minus character.

59 11 * * 1-5
This pattern is equivalent to the previous one.

The slash character can be used to identify periodic values, in the form a/b. A sub-pattern with the slash character is satisfied when the value on the left divided by the one on the right gives an integer result (a % b == 0).

*/15 9-17 * * *
This pattern causes a task to be launched every 15 minutes between the 9th and 17th hour of the day (9:00, 9:15, 9:30, 9:45 and so on... note that the last execution will be at 17:45).

All the fresh described syntax rules can be used together.

* 12 10-16/2 * *
This pattern causes a task to be launched every minute during the 12th hour of the day, but only if the day is the 10th, the 12th, the 14th or the16th of the month.

* 12 1-15,17,20-25 * *
This pattern causes a task to be launched every minute during the 12th hour of the day, but the day of the month must be between the 1st and the 15th, the 20th and the 25, or at least it must be the 17th.

Finally cron4j lets you combine more scheduling patterns into one, with the pipe character:

0 5 * * *|8 10 * * *|22 17 * * *
This pattern causes a task to be launched every day at 05:00, 10:08 and 17:22.

Author:
Carlo Pelliccia

Constructor Summary
Scheduler()
           
 
Method Summary
 void deschedule(java.lang.Object id)
          This methods cancels the scheduling of a task.
 java.lang.Runnable getTaskRunnable(java.lang.Object id)
          This method retrieves the Runnable object of a previously scheduled task.
 java.lang.String getTaskSchedulingPattern(java.lang.Object id)
          This method retrieves the scheduling pattern of a previously scheduled task.
 void reschedule(java.lang.Object id, java.lang.String schedulingPattern)
          This method changes the scheduling pattern of a task.
 java.lang.Object schedule(java.lang.String schedulingPattern, java.lang.Runnable task)
          This method schedules a task execution.
 void start()
          This method starts the scheduler.
 void stop()
          This method stops the scheduler execution.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Scheduler

public Scheduler()
Method Detail

schedule

public java.lang.Object schedule(java.lang.String schedulingPattern,
                                 java.lang.Runnable task)
                          throws InvalidPatternException
This method schedules a task execution.

Parameters:
schedulingPattern - The scheduling pattern for the task.
task - The task, as a plain Runnable object.
Returns:
The task auto-generated ID assigned by the scheduler. This ID can be used later to reschedule and deschedule the task, and also to retrieve informations about it.
Throws:
InvalidPatternException - If the supplied pattern is not valid.

reschedule

public void reschedule(java.lang.Object id,
                       java.lang.String schedulingPattern)
                throws InvalidPatternException
This method changes the scheduling pattern of a task.

Parameters:
id - The ID assigned to the previously scheduled task.
schedulingPattern - The new scheduling pattern for the task.
Throws:
InvalidPatternException - If the supplied pattern is not valid.

deschedule

public void deschedule(java.lang.Object id)
This methods cancels the scheduling of a task.

Parameters:
id - The ID of the task.

getTaskRunnable

public java.lang.Runnable getTaskRunnable(java.lang.Object id)
This method retrieves the Runnable object of a previously scheduled task.

Parameters:
id - The task ID.
Returns:
The Runnable object of the task, or null if the task was not found.

getTaskSchedulingPattern

public java.lang.String getTaskSchedulingPattern(java.lang.Object id)
This method retrieves the scheduling pattern of a previously scheduled task.

Parameters:
id - The task ID.
Returns:
The scheduling pattern of the task, or null if the task was not found.

start

public void start()
           throws java.lang.IllegalStateException
This method starts the scheduler. When the scheduled is started the supplied tasks are executed at the given moment.

Throws:
java.lang.IllegalStateException - Thrown if this scheduler is already started.

stop

public void stop()
          throws java.lang.IllegalStateException
This method stops the scheduler execution. Before returning it waits the end of all the running tasks previously launched. Once the scheduler has been stopped it can be started again with a start() call.

Throws:
java.lang.IllegalStateException - Thrown if this scheduler is not started.