it.sauronsoftware.cron4j
Class Scheduler

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

public class Scheduler
extends java.lang.Object

The cron4j scheduler.

Author:

Carlo Pelliccia

Constructor Summary

Scheduler()
It builds and prepares a brand new Scheduler instance.

Method Summary

void	addSchedulerListener(SchedulerListener listener) Adds a SchedulerListener to the scheduler.
void	addTaskCollector(TaskCollector collector) Adds a custom TaskCollector instance to the scheduler.
void	deschedule(java.lang.Object id) Deprecated. Use deschedule(String).
void	deschedule(java.lang.String id) This methods cancels the scheduling of a task.
void	descheduleFile(java.io.File file) Removes a File instance previously scheduled with the scheduleFile(File) method.
TaskExecutor[]	getExecutingTasks() Returns an array containing any currently executing task, in the form of TaskExecutor objects.
java.lang.Object	getGuid() It returns the GUID for this scheduler.
java.io.File[]	getScheduledFiles() Returns an array containing any File previously scheduled with the scheduleFile(File) method.
SchedulerListener[]	getSchedulerListeners() Returns an array containing any SchedulerListener previously registered with the addSchedulerListener(SchedulerListener) method.
SchedulingPattern	getSchedulingPattern(java.lang.String id) This method retrieves a previously scheduled task scheduling pattern.
Task	getTask(java.lang.String id) This method retrieves a previously scheduled task.
TaskCollector[]	getTaskCollectors() Returns an array containing any custom TaskCollector instance previously registered in the scheduler with the addTaskCollector(TaskCollector) method.
java.lang.Runnable	getTaskRunnable(java.lang.Object id) Deprecated. Use getTask(String).
java.lang.String	getTaskSchedulingPattern(java.lang.Object id) Deprecated. Use getSchedulingPattern(String).
java.util.TimeZone	getTimeZone() Returns the time zone applied by the scheduler.
boolean	isDaemon() Tests whether this scheduler is a daemon scheduler.
boolean	isStarted() Tests if this scheduler is started.
TaskExecutor	launch(Task task) Executes immediately a task, without scheduling it.
void	removeSchedulerListener(SchedulerListener listener) Removes a SchedulerListener previously registered with the addSchedulerListener(SchedulerListener) method.
void	removeTaskCollector(TaskCollector collector) Removes a previously registered custom TaskCollector instance.
void	reschedule(java.lang.Object id, java.lang.String schedulingPattern) Deprecated. Use reschedule(String, String).
void	reschedule(java.lang.String id, SchedulingPattern schedulingPattern) This method changes the scheduling pattern of a task.
void	reschedule(java.lang.String id, java.lang.String schedulingPattern) This method changes the scheduling pattern of a task.
java.lang.String	schedule(SchedulingPattern schedulingPattern, Task task) This method schedules a task execution.
java.lang.String	schedule(java.lang.String schedulingPattern, java.lang.Runnable task) This method schedules a task execution.
java.lang.String	schedule(java.lang.String schedulingPattern, Task task) This method schedules a task execution.
void	scheduleFile(java.io.File file) Adds a File instance to the scheduler.
void	setDaemon(boolean on) Marks this scheduler daemon flag.
void	setTimeZone(java.util.TimeZone timezone) Sets the time zone applied by the scheduler.
void	start() This method starts the scheduler.
void	stop() This method stops the scheduler execution.

Methods inherited from class java.lang.Object

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

Constructor Detail

Scheduler

public Scheduler()

It builds and prepares a brand new Scheduler instance.

Method Detail

getGuid

public java.lang.Object getGuid()

It returns the GUID for this scheduler.

Returns:

The GUID for this scheduler.

setTimeZone

public void setTimeZone(java.util.TimeZone timezone)

Sets the time zone applied by the scheduler.

Current system time is adapted to the supplied time zone before comparing it with registered scheduling patterns. The result is that any supplied scheduling pattern is treated according to the specified time zone. In example, suppose:

• System time: 10:00
• System time zone: GMT+1
• Scheduler time zone: GMT+3

The scheduler, before comparing system time with patterns, translates 10:00 from GMT+1 to GMT+3. It means that 10:00 becomes 12:00. The resulted time is then used by the scheduler to activate tasks. So, in the given configuration at the given moment, any task scheduled as 0 12 * * * will be executed, while any 0 10 * * * will not.

Parameters:

timezone - The time zone applied by the scheduler.

getTimeZone

public java.util.TimeZone getTimeZone()

Returns the time zone applied by the scheduler.

Returns:

The time zone applied by the scheduler.

isDaemon

public boolean isDaemon()

Tests whether this scheduler is a daemon scheduler.

Returns:

true if this scheduler is a daemon scheduler; false otherwise.

setDaemon

public void setDaemon(boolean on)
               throws java.lang.IllegalStateException

Marks this scheduler daemon flag. When a scheduler is marked as a daemon scheduler it spawns only daemon threads. The Java Virtual Machine exits when the only threads running are all daemon threads. This method must be called before the scheduler is started.

Parameters:

on - If true, the scheduler will spawn only daemon threads.

Throws:

java.lang.IllegalStateException - If the scheduler is started.

isStarted

public boolean isStarted()

Tests if this scheduler is started.

Returns:

true if the scheduler is started, false if it is stopped.

scheduleFile

public void scheduleFile(java.io.File file)

Adds a File instance to the scheduler. Every minute the file will be parsed. The scheduler will execute any declared task whose scheduling pattern matches the current system time. See CronParser documentation for informations about the file contents syntax.

Parameters:

file - The File instance.

descheduleFile

public void descheduleFile(java.io.File file)

Removes a File instance previously scheduled with the scheduleFile(File) method.

Parameters:

file - The File instance.

getScheduledFiles

public java.io.File[] getScheduledFiles()

Returns an array containing any File previously scheduled with the scheduleFile(File) method.

Returns:

An array containing any File previously scheduled with the scheduleFile(File) method.

addTaskCollector

public void addTaskCollector(TaskCollector collector)

Adds a custom TaskCollector instance to the scheduler. The supplied object, once added to the scheduler, will be query every minute for its task list. The scheduler will execute any of the returned tasks whose scheduling pattern matches the current system time.

Parameters:

collector - The custom TaskCollector instance.

removeTaskCollector

public void removeTaskCollector(TaskCollector collector)

Removes a previously registered custom TaskCollector instance.

Parameters:

collector - The custom TaskCollector instance.

getTaskCollectors

public TaskCollector[] getTaskCollectors()

Returns an array containing any custom TaskCollector instance previously registered in the scheduler with the addTaskCollector(TaskCollector) method.

Returns:

An array containing any custom TaskCollector instance previously registered in the scheduler with the addTaskCollector(TaskCollector) method.

addSchedulerListener

public void addSchedulerListener(SchedulerListener listener)

Adds a SchedulerListener to the scheduler. A SchedulerListener is notified every time a task is launching, has succeeded or has failed.

Parameters:

listener - The listener.

removeSchedulerListener

public void removeSchedulerListener(SchedulerListener listener)

Removes a SchedulerListener previously registered with the addSchedulerListener(SchedulerListener) method.

Parameters:

listener - The listener.

getSchedulerListeners

public SchedulerListener[] getSchedulerListeners()

Returns an array containing any SchedulerListener previously registered with the addSchedulerListener(SchedulerListener) method.

Returns:

An array containing any SchedulerListener previously registered with the addSchedulerListener(SchedulerListener) method.

getExecutingTasks

public TaskExecutor[] getExecutingTasks()

Returns an array containing any currently executing task, in the form of TaskExecutor objects. Each running task is executed by a different thread. A TaskExecutor object allows the control of the running task. The inner Task representation could be retrieved, the status of the task could be detected and the thread could be interrupted using any standard Thread method ( Thread.interrupt(), etc.

Returns:

An array containing any currently executing task, in the form of TaskExecutor objects.

schedule

public java.lang.String 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.

schedule

public java.lang.String schedule(java.lang.String schedulingPattern,
                                 Task 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.

Since:

2.0

schedule

public java.lang.String schedule(SchedulingPattern schedulingPattern,
                                 Task task)

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.

Since:

2.0

reschedule

public void reschedule(java.lang.Object id,
                       java.lang.String schedulingPattern)
                throws InvalidPatternException

Deprecated. Use reschedule(String, String).

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.

reschedule

public void reschedule(java.lang.String 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.

reschedule

public void reschedule(java.lang.String id,
                       SchedulingPattern schedulingPattern)

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.

Since:

2.0

deschedule

public void deschedule(java.lang.Object id)

Deprecated. Use deschedule(String).

This methods cancels the scheduling of a task.

Parameters:

id - The ID of the task.

deschedule

public void deschedule(java.lang.String id)

This methods cancels the scheduling of a task.

Parameters:

id - The ID of the task.

getTask

public Task getTask(java.lang.String id)

This method retrieves a previously scheduled task.

Parameters:

id - The task ID.

Returns:

The requested task, or null if the task was not found.

Since:

2.0

getSchedulingPattern

public SchedulingPattern getSchedulingPattern(java.lang.String id)

This method retrieves a previously scheduled task scheduling pattern.

Parameters:

id - The task ID.

Returns:

The requested scheduling pattern, or null if the task was not found.

Since:

2.0

getTaskRunnable

public java.lang.Runnable getTaskRunnable(java.lang.Object id)

Deprecated. Use getTask(String).

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)

Deprecated. Use getSchedulingPattern(String).

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.

launch

public TaskExecutor launch(Task task)

Executes immediately a task, without scheduling it.

Parameters:

task - The task.

Returns:

The TaskExecutor executing the given task.

Throws:

java.lang.IllegalStateException - If the scheduler is not started.

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.