The Carbon Scheduler Module

What Can Be Scheduled?

Any component method with no arguments can be scheduled as a task within the Scheduler service. Components can also implement the Scheduable interface in order to provide a runScheduledTask method that will be the default scheduled method. If a component does not implement the org.sape.carbon.services.scheduler.Schedulable interface, the scheduler must be configured with the name of the method to execute.

Example of Schedulable Component

package org.sape.carbon.services.cache;

import java.util.Map;

import org.sape.carbon.core.component.FunctionalInterface;
import org.sape.carbon.services.scheduler.Schedulable;

public interface Cache extends Map, FunctionalInterface, Schedulable {

    void refreshAll() throws CacheLoadException;

}

This service uses a java.util.Timer behind the scenes to schedule tasks. Follow the guidelines given by that class for creating tasks.

Scheduling a task

The Scheduler Service has no public methods. Tasks can only be scheduled by changing the scheduler's configuration.

Scheduler Service Configuration

The default implementation of the Scheduler Service supports 2 types of tasks: fixed-rate and fixed-delay. The following definitions of fixed-rate and fixed-delay are reproduced from the java.util.Timer javadoc:

Fixed-Rate Execution

In fixed-rate execution, each execution is scheduled relative to the scheduled execution time of the initial execution. If an execution is delayed for any reason (such as garbage collection or other background activity), two or more executions will occur in rapid succession to "catch up." In the long run, the frequency of execution will be exactly the reciprocal of the specified period (assuming the system clock underlying Object.wait(long) is accurate).

Fixed-rate execution is appropriate for recurring activities that are sensitive to absolute time, such as ringing a chime every hour on the hour, or running scheduled maintenance every day at a particular time. It is also appropriate for for recurring activities where the total time to perform a fixed number of executions is important, such as a countdown timer that ticks once every second for ten seconds. Finally, fixed-rate execution is appropriate for scheduling multiple repeating timer tasks that must remain synchronized with respect to one another.

Fixed-Delay Execution

In fixed-delay execution, each execution is scheduled relative to the actual execution time of the previous execution. If an execution is delayed for any reason (such as garbage collection or other background activity), subsequent executions will be delayed as well. In the long run, the frequency of execution will generally be slightly lower than the reciprocal of the specified period (assuming the system clock underlying Object.wait(long) is accurate).

Fixed-delay execution is appropriate for recurring activities that require "smoothness." In other words, it is appropriate for activities where it is more important to keep the frequency accurate in the short run than in the long run. This includes most animation tasks, such as blinking a cursor at regular intervals. It also includes tasks wherein regular activity is performed in response to human input, such as automatically repeating a character as long as a key is held down.

Fixed-Rate Task Configuration

The org.sape.carbon.services.scheduler.FixedRateTaskConfiguration configuration interface is used to create fixed-rate tasks within the Scheduler Service. Fixed-rate tasks are scheduled to execute at fixed times (e.g. every hour on the hour or every day at 3:30 AM). Available rates are mintutely, hourly, daily, weekly, monthly (every 30 days), and annually (every 365 days). The same task can be scheduled multiple times to achieve rates in between (e.g. twice a day). If the frequency of the task execution is more important than when the task executes, a fixed delay task may be more appropriate.

Valid values for Minute are 0 to 59 inclusive. Valid values for Hour are 0 to 23 inclusive (note no AM or PM). Valid values for DayOfMonth are 1 to 31 inclusive. Month is specified by org.sape.carbon.core.util.calendar.MonthEnum. DayOfWeek is specified by org.sape.carbon.core.util.calendar.DayOfWeekEnum.

The scheduling behavior of FixedRateTasks are as follows:

• If Minute is not specifed, the task is schedule to start at the beginning of each minute. An InvalidConfiguraitonException is thrown if other configuration information is specified.
• If Minute is specifed, but Hour is not, the task is scheduled to run hourly at the minute specifed by Minute. An InvalidConfiguraitonException is thrown if any of DayOfMonth, Month, and DayOfWeek are specifed.
• If Minute and Hour are specifed, but DayOfWeek and DayOfMonth are not, the task is scheduled to run daily at the specified time. An InvalidConfiguraitonException is thrown if Month is specifed.
• If Minute, Hour, and DayOfMonth are specifed, but Month is not, the task is scheduled to run every 30 days starting at the specified day and time. An InvalidConfiguraitonException is thrown if DayOfWeek is specifed.
• If Minute, Hour, DayOfMonth, and Month are specifed, the task is scheduled to run every 365 days starting at the specified date and time. An InvalidConfiguraitonException is thrown if DayOfWeek is specifed.
• If Minute, Hour, and DayOfWeek are specifed, but DayOfMonth and Month are not, the task is scheduled to run every 7 days starting at the specified day and time. An InvalidConfiguraitonException is thrown if Month is specifed.

Examples of FixedRateTaskConfigurations

     <!-- every hour on the hour -->
     <FixedRateTask>
         <Minute>0</Minute>
         <SchedulableComponent>ref:///scheduler/test/TestSchedulableComponent</SchedulableComponent>
        <ScheduledMethod>doWork</ScheduledMethod>
     </FixedRateTask>

     <!-- every day at midnight -->
     <FixedRateTask>
         <Minute>0</Minute>
         <Hour>0</Hour>
         <SchedulableComponent>ref:///scheduler/test/TestSchedulableComponent</SchedulableComponent>
     </FixedRateTask>

     <!-- every monday at midnight -->
     <FixedRateTask>
         <Minute>0</Minute>
         <Hour>0</Hour>
         <DayOfWeek>Monday</DayOfWeek>
         <SchedulableComponent>ref:///scheduler/test/TestSchedulableComponent</SchedulableComponent>
     </FixedRateTask>

     <!-- every 26th of every month at midnight -->
     <FixedRateTask>
         <Minute>0</Minute>
         <Hour>0</Hour>
         <DayOfMonth>26</DayOfMonth>
         <SchedulableComponent>ref:///scheduler/test/TestSchedulableComponent</SchedulableComponent>
     </FixedRateTask>

     <!-- every march 1st a midnight -->
     <FixedRateTask>
         <Minute>0</Minute>
         <Hour>0</Hour>
         <DayOfMonth>1</DayOfMonth>
         <Month>March</Month>
         <SchedulableComponent>ref:///scheduler/test/TestSchedulableComponent</SchedulableComponent>
     </FixedRateTask>

Fixed-Delay Task Configuration

The org.sape.carbon.services.scheduler.FixedDelayTaskConfiguration is used to configure tasks where the repeat period is more important than when the tasks are executed. Note that this period is sensitive to when the timer is started. If the scheduler service is paused or restarted (either via lifecycle methods or a JVM restart), the timer is restarted as well. The configuration interface supports setting an initial delay that defines how long to wait before executing the task for the first time and a period that specifies how often to run the task.

Examples of FixedDelayTaskConfigurations

     <!-- no initial dely, executing every hour-->
     <FixedDelayTask>
         <Period>360000</Period>
         <SchedulableComponent>ref:///scheduler/test/TestSchedulableComponent</SchedulableComponent>
         <ScheduledMethod>doWork</ScheduledMethod>
     </FixedDelayTask>

     <!-- one hour initial dely, executing every minute-->
     <FixedDelayTask>
         <InitialDelay>360000</InitialDelay>
         <Period>60000</Period>
         <SchedulableComponent>ref:///scheduler/test/TestSchedulableComponent</SchedulableComponent>
     </FixedDelayTask>