Module quartz_sched

Description
Data Types
Function Index
Function Details

Quartz Time Scheduler.

Version: 1.1.0

Authors: Aleph Archives Ltd. [web site: http://aleph-archives.com/].

Description

Quartz Time Scheduler.

Quartz jobs can be scheduled "a la CRON" by using the methods quartz:schedule/4/5 methods. These calls take as a first argument (or second for schedule/5) a "Time Specification" that is used to compute the next time the job should be launched on.

The specification is a tuple of the form:

{ {Year,Month,Day}, WeekDay, {Hour, Minute, Second} }

Alternatively the WeekDay can be ommited for simplification:

{ {Year,Month,Day}, {Hour, Minute, Second} }

Each field has a fixed range of allowed values defined as:

 
      field          allowed values
      -----          --------------
      minute         0-59
      hour           0-23
      day of week    1-7 (1 is Monday, or use names : mon, tue, wed, thu, fri, sat, sun)
      day            1-31
      month          1-12
      year           0-2200 (don't expect anything more than that to be useful)

The most basic "Time Specification" is any valid calendar:datetime() tuple.

Example: A job scheduled using the specification :

{{2012, 12, 21}, {0, 0, 0}}

(probably by a Mayan shaman who wanted to unleach the wrath of an ancient prophecy) would have been started by quartz exactly the 21st Dec, 2012 at 00:00:00.

To allow recurrence, all fields can take values with special semantics. The combination of regular and special values is powerful and flexible enough to express complex schedules. The special values are described below:

The wildcard (the atom '*')

{{'*', 12, 21}, {0, 0, 0}} will start the job the 21st Dec of each year at 00:00:00
{{'*', '*', '*'}, {0, 0, 0}} will start the job each day at 00:00:00
{{'*', '*', '*'}, sat, {0, 0, 0}} will start the job each Saturday at 00:00:00

The range notation ({Start , End} or {Start, End, Step})

{{{2012, 2014}, 12, 21}, {0, 0, 0}} will start the job the 21st Dec of 2012,2013,2014 at 00:00:00
{{'*', '*', '*'}, {{0,23,2}, 0, 0}} will start the job each day at the even hours (0,2,4...,20,22)
{{'*', '*', '*'}, {{22,1}, 0, 0}} wrapping ranges are possible (the increment is also possible for all fields but day), this expression will schedule the job for 22h, 23h, 0h and 1h of each day

The list can be used to restrict a field to a specific list of values

{[2012,2015,2019], 12, 21}, {0, 0, 0}} will start the job the 21st Dec of 2012,2015,2019 at 00:00:00
{{'*', '*', '*'}, {{[0,12],'*','*'}} will start the job each day at midnight and noon
{{'*', '*', '*'}, {[{0,3},{5,7}], 0, 0}} list of ranges are also supported

'last' means the upper value of the range allowed for the field

{{'*', 2, last}, {0, 0, 0}} will start the job the last day of Feb (28th or 29th) of each year
{{'*', 2, last}, {0, 0, 0}} will start the job the last day of Feb (28th or 29th) of each year

UNIONS can be used to compose different time specifications. It can be seen as an UNION between all the possible results of each time specification, and is semantically equivalent to evaluating each specification, then choosing the closest result. This is useful to describe schedules like : "Do it at 12 the odd days, and at 10 the even ones."

[{{'*','*',{1,15}},{12,0,0}}, {{'*','*',{16,last}},{13,0,0}}] will start a job 12am from the 1st to the 15th, and at 1pm from the 16th to the last day of the month

To lighten the time specification syntax, some shortcuts are provided

{{H,M,S}} is equivalent to {daily, {H,M,S}}
{'*', {...}} is equivalent to : {{'*','*','*'}, {...}}
{daily, {...}} is equivalent to : {{'*','*','*'}, {...}}
{weekly, WeekDay, {...}} is equivalent to : {{'*','*','*'}, WeekDay, {...}}
{monthly, {...}} is equivalent to : {{'*','*',1}, {...}}
{monthly, WeekDay, {...}} is equivalent to : {{'*','*',{1,7}}, WeekDay, {...}} ( read the first WeekDay of each month )
{{monthly,Day}, {...}} is equivalent to : {{'*','*',Day}, {...}}
{annually, {...}} is equivalent to : {{'*',1,1}, {...}}
{annually, WeekDay, {...}} is equivalent to : {{'*',1,{1,7}},WeekDay, {...}} ( read the first WeekDay of each year )

Note that the jobs are executed according to locale time. This means that non-existent times, such as the "missing hours" during the daylight savings time conversion, will never match, causing jobs scheduled during the "missing times" not to be run. Similarly, times that occur more than once (again, during the daylight savings time conversion) will cause matching jobs to be run twice.

Data Types

date_sched()

date_sched() = {year_sched(), month_sched(), day_sched()} | daily | weekly | monthly | annualy | '*'

day_sched()

day_sched() = '*' | day_sched_range()

day_sched_range()

day_sched_range() = [day_sched_range()] | {day_sched_range_comp(), day_sched_range_comp()} | {day_sched_range_comp(), day_sched_range_comp(), non_neg_integer()} | day_sched_range_comp()

day_sched_range_comp()

day_sched_range_comp() = last | calendar:day()

hour_sched()

hour_sched() = '*' | hour_sched_range()

hour_sched_range()

hour_sched_range() = [hour_sched_range()] | {hour_sched_range_comp(), hour_sched_range_comp()} | {hour_sched_range_comp(), hour_sched_range_comp(), non_neg_integer()} | hour_sched_range_comp()

hour_sched_range_comp()

hour_sched_range_comp() = last | calendar:hour()

minute_sched()

minute_sched() = '*' | minute_sched_range()

minute_sched_range()

minute_sched_range() = [minute_sched_range()] | {minute_sched_range_comp(), minute_sched_range_comp()} | {minute_sched_range_comp(), minute_sched_range_comp(), non_neg_integer()} | minute_sched_range_comp()

minute_sched_range_comp()

minute_sched_range_comp() = last | calendar:minute()

month_sched()

month_sched() = '*' | month_sched_range()

month_sched_range()

month_sched_range() = [month_sched_range()] | {month_sched_range_comp(), month_sched_range_comp()} | {month_sched_range_comp(), month_sched_range_comp(), non_neg_integer()} | month_sched_range_comp()

month_sched_range_comp()

month_sched_range_comp() = last | calendar:month()

sched()

sched() = {date_sched(), time_sched()} | {date_sched(), wday_sched(), {hour_sched(), minute_sched(), second_sched()}}

second_sched()

second_sched() = '*' | second_sched_range()

second_sched_range()

second_sched_range() = [second_sched_range()] | {second_sched_range_comp(), second_sched_range_comp()} | {second_sched_range_comp(), second_sched_range_comp(), non_neg_integer()} | second_sched_range_comp()

second_sched_range_comp()

second_sched_range_comp() = last | calendar:second()

time_sched()

time_sched() = {hour_sched(), minute_sched(), second_sched()} | hourly | minute

timespec()

timespec() = sched() | [sched()]

wday_sched()

wday_sched() = '*' | wday_sched_range()

wday_sched_range()

wday_sched_range() = [wday_sched_range()] | {wday_sched_range_comp(), wday_sched_range_comp()} | {wday_sched_range_comp(), wday_sched_range_comp(), non_neg_integer()} | wday_sched_range_comp()

wday_sched_range_comp()

wday_sched_range_comp() = last | sun | mon | tue | wed | thu | fri | sat | calendar:daynum()

year_sched()

year_sched() = '*' | year_sched_range()

year_sched_range()

year_sched_range() = [year_sched_range()] | {year_sched_range_comp(), year_sched_range_comp()} | {year_sched_range_comp(), year_sched_range_comp(), non_neg_integer()} | year_sched_range_comp()

year_sched_range_comp()

year_sched_range_comp() = calendar:year()

Function Index

is_valid_spec/1	Returns 'ok' if the given "TimeSpec" is correctly evaluated.
next/1	Equivalent to next(TimeSpec, calendar:now_to_local_time(now())).
next/2	Returns the datetime immediately following the "BaseDate" and that match the "TimeSpec" specification.
sample/2	Same as sample(TimeSpec, calendar:now_to_local_time(now()), N).
sample/3	Returns a list of at most "N" datetimes following the "BaseDate" and that match the "TimeSpec" specification.
sooner_date/2

If no match can be found, returns the atom 'error_unforeseeable_future'.