Class CronTrigger
- java.lang.Object
-
- jakarta.enterprise.concurrent.CronTrigger
-
- All Implemented Interfaces:
Trigger
,ZonedTrigger
public class CronTrigger extends Object implements ZonedTrigger
Cron-based
Trigger
implementation, which supports 5 or 6 fields delimited by a single space character, plus aZoneId
. Basic cron syntax is supported. For more advanced scenarios, you can subclass this implementation or combine multipleCronTrigger
instances in aTrigger
implementation of your own.Cron Expression Fields seconds (optional) 0-59, *. When absent, 0 is assumed minutes 0-59, * hours 0-23, * dayOfMonth 0-31, *, L month 1-12, JAN-DEC, January-December, * dayOfWeek SUN-SAT, Sunday-Saturday, 0-7, *. 0 and 7 both represent Sunday: 0 to designate the first day of the week, and 7 for consistency with DayOfWeek
.
Cron Expression Syntax ,
delimits lists for all fields. For example, MON,WED,FRI
orMAY,SEP
-
delimits ranges for all fields. For example, MON-FRI
or9-17
/
specifies a repeating increment for all fields except dayOfWeek. For example, 6/7
for thehours
field equates to6,13,20
.#
specifies an ordinal day of week. For example, FRI#1,SAT#L
is the first Friday and last Saturday of the month.#
cannot be used within ranges (-
) and increments (/
).*
indicates any value is permitted. L
indicates the last day of the month. 2L
indicates the second-to-last day, and so forth.
Cron Expression Examples 0 * * * *
every hour at the top of the hour 0 9-17 * * MON-FRI
weekdays from 9am to 5pm, at the top of each hour 0 13/3 * MAY-SEP SAT,SUN
weekends from May to September, every 3 hours, starting at 1pm 30 10 * APR,AUG TUE#2,TUE#L
second and last Tuesdays of April and August at 10:30am 15 22 4 10,20,L * *
4:22:15 AM on the 10th, 20th, and last day of every month 0 8-11,13-16 2L JAN-MAR *
8AM-11AM and 1PM-4PM on the second-to-last day of January, February, and March A constructor is provided that accepts a cron expression such as the above and a timezone id. For example,
trigger = new CronTrigger("0 7 * SEP-MAY MON-FRI", ZoneId.of("America/New_York"));
Another constructor allows cron fields to be specified in a fluent manner, in any order. For example,
trigger = new CronTrigger(ZoneId.of("America/Los_Angeles")) .months(Month.DECEMBER) .daysOfMonth(24) .hours(16, 18);
The
getNextRunTime
method of this trigger determines the next run time based on the cron schedule. TheskipRun
method always returns false unless overridden by a subclass.Methods of this class that configure the cron expression fields are not thread safe. It is the responsibility of the caller to ensure that initialization of the
CronTrigger
happens before it is supplied to aManagedScheduledExecutorService
and that theCronTrigger
is not subsequently modified.You can subclass
CronTrigger
to provide for more complex logic, such as in the following example of combining two triggers to schedule twice-a-month payroll on the 15th and last day of month or the prior Fridays when the former fall on a weekend:public class PayrollTrigger extends CronTrigger { private final CronTrigger fridaysBeforeWeekendPayrollDay; PayrollTrigger() { // Every 15th and last day of the month that is a weekday, super("0 10 15,L * MON-FRI", ZoneId.of("America/Chicago")); // Every 13th, 14th, third-to-last, and second-to-last day of the month that is a Friday, fridaysBeforeWeekendPayrollDay = new CronTrigger( "0 10 13,14,3L,2L * FRI", getZoneId()); } public ZonedDateTime getNextRunTime(LastExecution lastExec, ZonedDateTime scheduledAt) { ZonedDateTime time1 = super.getNextRunTime(lastExec, scheduledAt); ZonedDateTime time2 = fridaysBeforeWeekendPayrollDay.getNextRunTime(lastExec, scheduledAt); return time1.isBefore(time2) ? time1 : time2; } }
- Since:
- 3.0
-
-
Constructor Summary
Constructors Constructor Description CronTrigger(String cron, ZoneId zone)
Constructor that accepts a cron expression.CronTrigger(ZoneId zone)
Constructor for the fluent configuration pattern.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description CronTrigger
daysOfMonth(int... d)
Configure the day-of-month cron field, overwriting any previous value for day-of-month.CronTrigger
daysOfMonth(String d)
Configure the day-of-month cron field, overwriting any previous value for day-of-month.CronTrigger
daysOfWeek(String d)
Configure the day-of-week cron field, overwriting any previous value for day-of-week.CronTrigger
daysOfWeek(DayOfWeek... d)
Configure the day-of-week cron field, overwriting any previous value for day-of-week.ZonedDateTime
getNextRunTime(LastExecution lastExecutionInfo, ZonedDateTime taskScheduledTime)
Using the cron schedule, and based on the end of the most recent execution (or absent that, the initial scheduling time), retrieve the next time that the task should run after.ZoneId
getZoneId()
Returns the timezone to use forZonedDateTime
that is supplied to thegetNextRunTime
andskipRun
methods.CronTrigger
hours(int... h)
Configure the hours cron field, overwriting any previous value for hours.CronTrigger
hours(String h)
Configure the hours cron field, overwriting any previous value for hours.CronTrigger
minutes(int... m)
Configure the minutes cron field, overwriting any previous value for minutes.CronTrigger
minutes(String m)
Configure the minutes cron field, overwriting any previous value for minutes.CronTrigger
months(String m)
Configure the months cron field, overwriting any previous value for months.CronTrigger
months(Month... m)
Configure the month cron field, overwriting any previous value for month.protected ZonedDateTime
next(ZonedDateTime from)
Advance to the next date/time according to the cron schedule.CronTrigger
seconds(int... s)
Configure the seconds cron field, overwriting any previous value for seconds.CronTrigger
seconds(String s)
Configure the seconds cron field, overwriting any previous value for seconds.String
toString()
Readable representation of the CronTrigger, which displays fields in list form or with the * character for brevity.-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
-
Methods inherited from interface jakarta.enterprise.concurrent.ZonedTrigger
getNextRunTime, skipRun, skipRun
-
-
-
-
Constructor Detail
-
CronTrigger
public CronTrigger(String cron, ZoneId zone)
Constructor that accepts a cron expression.- Parameters:
cron
- cron expression.zone
- timezone ID to use forZonedDateTime
that is supplied togetNextRunTime
andskipRun
methods. Null indicates to use the system default.
-
CronTrigger
public CronTrigger(ZoneId zone)
Constructor for the fluent configuration pattern. Seconds, minutes, and hours default to 0. The remaining fields default to *.- Parameters:
zone
- timezone ID to use forZonedDateTime
that is supplied togetNextRunTime
andskipRun
methods. Null indicates to use the system default.
-
-
Method Detail
-
getNextRunTime
public ZonedDateTime getNextRunTime(LastExecution lastExecutionInfo, ZonedDateTime taskScheduledTime)
Using the cron schedule, and based on the end of the most recent execution (or absent that, the initial scheduling time), retrieve the next time that the task should run after.- Specified by:
getNextRunTime
in interfaceZonedTrigger
- Parameters:
lastExecutionInfo
- information about the last execution of the task. This value will be null if the task has not yet run.taskScheduledTime
- the date/time at which theManagedScheduledExecutorService.schedule
method was invoked to schedule the task.- Returns:
- the date/time after which the next execution of the task should start.
- Throws:
DateTimeException
- if a next time cannot be determined from the cron expression.
-
getZoneId
public final ZoneId getZoneId()
Returns the timezone to use forZonedDateTime
that is supplied to thegetNextRunTime
andskipRun
methods.- Specified by:
getZoneId
in interfaceZonedTrigger
- Returns:
- timezone to use for operations on this trigger.
-
daysOfMonth
public CronTrigger daysOfMonth(int... d)
Configure the day-of-month cron field, overwriting any previous value for day-of-month.- Parameters:
d
- one or more day numbers ranging from 1 to 31.- Returns:
- this instance.
-
daysOfMonth
public CronTrigger daysOfMonth(String d)
Configure the day-of-month cron field, overwriting any previous value for day-of-month.- Parameters:
d
- dayOfMonth cron field. For example,15,L
.- Returns:
- this instance.
-
daysOfWeek
public CronTrigger daysOfWeek(DayOfWeek... d)
Configure the day-of-week cron field, overwriting any previous value for day-of-week.- Parameters:
d
- one or more days of the week.- Returns:
- this instance.
-
daysOfWeek
public CronTrigger daysOfWeek(String d)
Configure the day-of-week cron field, overwriting any previous value for day-of-week.- Parameters:
d
- dayOfWeek cron field. For example,MON-FRI,SAT#L
.- Returns:
- this instance.
-
hours
public CronTrigger hours(int... h)
Configure the hours cron field, overwriting any previous value for hours.- Parameters:
h
- one or more hour values ranging from 0 to 23.- Returns:
- this instance.
-
hours
public CronTrigger hours(String h)
Configure the hours cron field, overwriting any previous value for hours.- Parameters:
h
- hours cron field. For example,9-17
for 9am to 5pm.- Returns:
- this instance.
-
minutes
public CronTrigger minutes(int... m)
Configure the minutes cron field, overwriting any previous value for minutes.- Parameters:
m
- one or more minute values ranging from 0 to 59.- Returns:
- this instance.
-
minutes
public CronTrigger minutes(String m)
Configure the minutes cron field, overwriting any previous value for minutes.- Parameters:
m
- minutes cron field. For example,5/10
for 10 minute intervals starting at 5 minutes after the hour (:05, :15, :25, :35, :45, :55).- Returns:
- this instance.
-
months
public CronTrigger months(Month... m)
Configure the month cron field, overwriting any previous value for month.- Parameters:
m
- one or more months.- Returns:
- this instance.
-
months
public CronTrigger months(String m)
Configure the months cron field, overwriting any previous value for months.- Parameters:
m
- months cron field. For example,SEP-NOV,FEB-MAY
.- Returns:
- this instance.
-
seconds
public CronTrigger seconds(int... s)
Configure the seconds cron field, overwriting any previous value for seconds.- Parameters:
s
- one or more seconds values ranging from 0 to 59.- Returns:
- this instance.
-
seconds
public CronTrigger seconds(String s)
Configure the seconds cron field, overwriting any previous value for seconds.- Parameters:
s
- seconds cron field. For example,30
.- Returns:
- this instance.
-
toString
public String toString()
Readable representation of the CronTrigger, which displays fields in list form or with the * character for brevity.For example,
CronTrigger@89abcdef seconds 0, minutes 0, hours 9, *, months 3,6,9,12, SAT#2,SAT#4
-
next
protected ZonedDateTime next(ZonedDateTime from)
Advance to the next date/time according to the cron schedule.- Parameters:
from
- the date/time from which to compute the next time.- Returns:
- next date/time according to the cron schedule, or the original time if it matches.
-
-