Module quartz_sched

Quartz Time Scheduler.

Copyright 2010-2013 ALEPH ARCHIVES Ltd. All rights reserved.

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 '*') The range notation ({Start , End} or {Start, End, Step}) The list can be used to restrict a field to a specific list of values 'last' means the upper value of the range allowed for the field 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."

To lighten the time specification syntax, some shortcuts are provided

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/1Returns 'ok' if the given "TimeSpec" is correctly evaluated.
next/1Equivalent 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/2Same as sample(TimeSpec, calendar:now_to_local_time(now()), N).
sample/3Returns a list of at most "N" datetimes following the "BaseDate" and that match the "TimeSpec" specification.
sooner_date/2

Function Details

is_valid_spec/1

is_valid_spec(TimeSpec::timespec()) -> ok | {error, any()}

Returns 'ok' if the given "TimeSpec" is correctly evaluated. Otherwise, returns 'error'.

next/1

next(TimeSpec::timespec()) -> calendar:datetime() | error_unforeseeable_future

Equivalent to next(TimeSpec, calendar:now_to_local_time(now())).

next/2

next(TimeSpec::timespec(), BaseDate::calendar:datetime()) -> calendar:datetime() | error_unforeseeable_future

Returns the datetime immediately following the "BaseDate" and that match the "TimeSpec" specification.

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

sample/2

sample(TimeSpec::timespec(), Num::pos_integer()) -> [calendar:datetime()] | error_unforeseeable_future

Same as sample(TimeSpec, calendar:now_to_local_time(now()), N).

sample/3

sample(TimeSpec::timespec(), BaseDate::calendar:datetime(), Num::pos_integer()) -> [calendar:datetime()] | error_unforeseeable_future

Returns a list of at most "N" datetimes following the "BaseDate" and that match the "TimeSpec" specification. This can be used to check if the time specification gives the expected behaviour.

sooner_date/2

sooner_date(A, B) -> any()


Generated by EDoc, Feb 27 2013, 09:50:36.