NetKernel provides a task scheduling service similar to the Cron service on Unix systems.

The NetKernel Cron service is in the module urn:org:ten60:netkernel:util:cron and relies on OpenSymphony Quartz.

The NetKernel Cron service provides a control panel plugin for viewing and administering scheduled jobs, three accessors for programatically managing jobs and a custom log for tracking Cron events.

Job Specification

Cron provides two mechanisms for specifying jobs:

1. A module can expose entrypoints of the category of "cron" to define jobs that are to be scheduled whenever the module is commisioned. These jobs are re-registered everytime cron restarts. Use this mechanism to define either oneshot execution of jobs (that run each time NetKernel starts) or repetitive execution of jobs that continue as long as the defining module is deployed.
2. Manually schedule jobs with the cronNew accessor. This is useful for ad hock scheduling of jobs in workflow situations. Jobs can also be removed with the cronDelete accessor.

The job scheduling specification conforms to this RelaxNG schema.

Here is a sample job specification:

Jobs fire a request at the external interface of a module. The module is determined by the context of the entrypoint or request so only the URI on the interface needs to be defined. A globally unique name must be specified for the job. The description is used only for the purposes of display in the control panel.

Two basic types of timing specification are supported by cron; this reflects the underlying Quartz implementation.

• cron A cron specification allows the complex declaration of job scheduling which is tied to the system clock and calendar.

  Field Name	Description
  startTime	The startTime field is an optional non-negative long integer. If startTime is omitted then the task starts immediately. If startTime is a small value (less than coordinated universal time (UTC)) then the value is considered relative from the time the job is instantiated. Otherwise the start time is considered a coordinated universal time (UTC) time.
  endTime	The endTime field is an optional non-negative long integer. If endTime is omitted then the task will run indefinitely bounded only by the number of repeats. endTime behaves similarly to startTime in that for a small value it is considered a relative time offset from now, larger values are considered as absolute coordinated universal time (UTC) time.
  expr	The cron expression as defined below.

  Here is the full specification copied verbatim from http://www.opensymphony.com/quartz/api/org/quartz/CronTrigger.html:
  

  For those unfamiliar with "cron", this means being able to create a firing schedule such as: "At 8:00am every Monday through Friday" or "At 1:30am every last Friday of the month".

  A "Cron-Expression" is a string comprised of 6 or 7 fields separated by white space. The 6 mandatory and 1 optional fields are as follows:
  

  Field Name		Allowed Values		Allowed Special Characters
  Seconds		0-59		, - * /
  Minutes		0-59		, - * /
  Hours		0-23		, - * /
  Day-of-month		1-31		, - * ? / L W C
  Month		1-12 or JAN-DEC		, - * /
  Day-of-Week		1-7 or SUN-SAT		, - * ? / L C #
  Year (Optional)		empty, 1970-2099		, - * /

  The '*' character is used to specify all values. For example, "*" in the minute field means "every minute".

  The '?' character is allowed for the day-of-month and day-of-week fields. It is used to specify 'no specific value'. This is useful when you need to specify something in one of the two fileds, but not the other. See the examples below for clarification.

  The '-' character is used to specify ranges For example "10-12" in the hour field means "the hours 10, 11 and 12".

  The ',' character is used to specify additional values. For example "MON,WED,FRI" in the day-of-week field means "the days Monday, Wednesday, and Friday".

  The '/' character is used to specify increments. For example "0/15" in the seconds field means "the seconds 0, 15, 30, and 45". And "5/15" in the seconds field means "the seconds 5, 20, 35, and 50". Specifying '*' before the '/' is equivalent to specifying 0 is the value to start with. Essentially, for each field in the expression, there is a set of numbers that can be turned on or off. For seconds and minutes, the numbers range from 0 to 59. For hours 0 to 23, for days of the month 0 to 31, and for months 1 to 12. The "/" character simply helps you turn on every "nth" value in the given set. Thus "7/6" in the month field only turns on month "7", it does NOT mean every 6th month, please note that subtlety.

  The 'L' character is allowed for the day-of-month and day-of-week fields. This character is short-hand for "last", but it has different meaning in each of the two fields. For example, the value "L" in the day-of-month field means "the last day of the month" - day 31 for January, day 28 for February on non-leap years. If used in the day-of-week field by itself, it simply means "7" or "SAT". But if used in the day-of-week field after another value, it means "the last xxx day of the month" - for example "6L" means "the last friday of the month". When using the 'L' option, it is important not to specify lists, or ranges of values, as you'll get confusing results.

  The 'W' character is allowed for the day-of-month field. This character is used to specify the weekday (Monday-Friday) nearest the given day. As an example, if you were to specify "15W" as the value for the day-of-month field, the meaning is: "the nearest weekday to the 15th of the month". So if the 15th is a Saturday, the trigger will fire on Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. However if you specify "1W" as the value for day-of-month, and the 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not 'jump' over the boundary of a month's days. The 'W' character can only be specified when the day-of-month is a single day, not a range or list of days.

  The 'L' and 'W' characters can also be combined for the day-of-month expression to yield 'LW', which translates to "last weekday of the month".

  The '#' character is allowed for the day-of-week field. This character is used to specify "the nth" XXX day of the month. For example, the value of "6#3" in the day-of-week field means the third Friday of the month (day 6 = Friday and "#3" = the 3rd one in the month). Other examples: "2#1" = the first Monday of the month and "4#5" = the fifth Wednesday of the month. Note that if you specify "#5" and there is not 5 of the given day-of-week in the month, then no firing will occur that month.

  The 'C' character is allowed for the day-of-month and day-of-week fields. This character is short-hand for "calendar". This means values are calculated against the associated calendar, if any. If no calendar is associated, then it is equivalent to having an all-inclusive calendar. A value of "5C" in the day-of-month field means "the first day included by the calendar on or after the 5th". A value of "1C" in the day-of-week field means "the first day included by the calendar on or after sunday".

  The legal characters and the names of months and days of the week are not case sensitive.

  Here are some full examples:
  

  Expression		Meaning
  "0 0 12 * * ?"		Fire at 12pm (noon) every day
  "0 15 10 ? * *"		Fire at 10:15am every day
  "0 15 10 * * ?"		Fire at 10:15am every day
  "0 15 10 * * ? *"		Fire at 10:15am every day
  "0 15 10 * * ? 2005"		Fire at 10:15am every day during the year 2005
  "0 * 14 * * ?"		Fire every minute starting at 2pm and ending at 2:59pm, every day
  "0 0/5 14 * * ?"		Fire every 5 minutes starting at 2pm and ending at 2:55pm, every day
  "0 0/5 14,18 * * ?"		Fire every 5 minutes starting at 2pm and ending at 2:55pm, AND fire every 5 minutes starting at 6pm and ending at 6:55pm, every day
  "0 0-5 14 * * ?"		Fire every minute starting at 2pm and ending at 2:05pm, every day
  "0 10,44 14 ? 3 WED"		Fire at 2:10pm and at 2:44pm every Wednesday in the month of March.
  "0 15 10 ? * MON-FRI"		Fire at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday
  "0 15 10 15 * ?"		Fire at 10:15am on the 15th day of every month
  "0 15 10 L * ?"		Fire at 10:15am on the last day of every month
  "0 15 10 ? * 6L"		Fire at 10:15am on the last Friday of every month
  "0 15 10 ? * 6L"		Fire at 10:15am on the last Friday of every month
  "0 15 10 ? * 6L 2002-2005"		Fire at 10:15am on every last friday of every month during the years 2002, 2003, 2004 and 2005
  "0 15 10 ? * 6#3"		Fire at 10:15am on the third Friday of every month

  Pay attention to the effects of '?' and '*' in the day-of-week and day-of-month fields!

  NOTES:

  • Support for the features described for the 'C' character is not complete.
  • Support for specifying both a day-of-week and a day-of-month value is not complete (you'll need to use the '?' character in on of these fields).
  • Be careful when setting fire times between mid-night and 1:00 AM - "daylight savings" can cause a skip or a repeat depending on whether the time moves back or jumps forward.

• simple A simple specification allows the declaration of a periodic task running between an optional start and end time.

  Field Name	Description
  startTime	The startTime field is an optional non-negative long integer. If startTime is omitted then the task starts immediately. If startTime is a small value (less than coordinated universal time (UTC)) then the value is considered relative from the time the job is instantiated. Otherwise the start time is considered a coordinated universal time (UTC) time.
  endTime	The endTime field is an optional non-negative long integer. If endTime is omitted then the task will run indefinitely bounded only by the number of repeats. endTime behaves similarly to startTime in that for a small value it is considered a relative time offset from now, larger values are considered as absolute coordinated universal time (UTC) time.
  repeatCount	The repeatCount field is an optional positive integer. If repeatCount is is omitted and repeatInterval is specified then the task will repeat indefinately. If repeatCount is specified then repeatInterval must be specified and the task will repeat that number of times.
  repeatInterval	The repeatInterval field is an optional positive long integer. Repeat interval must be specified if either endTime or repeatCount is specified. It is considered to be a millisecond period.

Additional data can be stored by cron alongside the state necessary for job execution. This is called user job data. Multiple name value pairs can be stored.

Control Panel Plugin

The cron module provides a control panel plugin which lists all scheduled jobs. It allows sorting, deleting, pausing and manual execution of jobs.

Accessors

Three accessors are provided for programmatic control of scheduled jobs: cronNew, cronDelete and cronList.

Logging

The cron module logs to a custom application log named "cron". The following logging levels are used:

Level	Usage
severe	used to log a failure to parse either persistent state during startup.
warning	used to log a failure to parse static jobs from entrypoints in modules during startup, if jobs have misfired due to downtime or if errors occur during the execution of jobs.
info	used to log routine actions performed during startup and shutdown and also manual actions performed using the control panel.
fine	used to log the scheduled execution of jobs.
finer	used to log the responses from successful execution of jobs.

Persistence of Jobs / Misfire

When cron is shutdown normally all active jobs are persisted. When cron starts again it checks to see if any persisted jobs should have fired during the downtime. If they should have then they are logged and issued immediately. Any jobs which are still active are reinstated.