Jakarta EE 11.0.0 · jakarta.enterprise.concurrent.CronTrigger

Cron-based Trigger implementation, which supports 5 or 6 fields delimited by a single space character, plus a ZoneId. Basic cron syntax is supported. For more advanced scenarios, you can subclass this implementation or combine multiple CronTrigger instances in a Trigger 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 `java.time.DayOfWeek`.

**Cron Expression Syntax**
`,`	delimits lists for all fields. For example, `MON,WED,FRI` or `MAY,SEP`
`-`	delimits ranges for all fields. For example, `MON-FRI` or `9-17`
`/`	specifies a repeating increment for all fields except dayOfWeek. For example, `6/7` for the `hours` field equates to `6,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. The skipRun 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 a ManagedScheduledExecutorService and that the CronTrigger 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;
    }
}

Field Summary

Modifier and Type	Field and Description
private static final int[]	ALL_DAYS_OF_MONTH
private static final int[]	ALL_DAYS_OF_WEEK
private static final int[]	ALL_MONTHS
private static final Map<String, Integer>	DAYS_OF_WEEK
private int[]	daysOfMonth
private int[]	daysOfWeek
private int[]	hours
private static final int	LAST
private int[]	minutes
private static final Map<String, Integer>	MONTHS
private int[]	months
private int[]	seconds
private static final int[]	ZERO
private final ZoneId	zone

Constructor Summary

Access	Constructor and Description
public	CronTrigger(final String cron expression. cron, final ZoneId timezone ID to use for `java.time.ZonedDateTime` that is supplied to `getNextRunTime` and `skipRun` methods. Null indicates to use the system default. zone) Constructor that accepts a cron expression.
public	CronTrigger(final ZoneId timezone ID to use for `java.time.ZonedDateTime` that is supplied to `getNextRunTime` and `skipRun` methods. Null indicates to use the system default. zone) Constructor for the fluent configuration pattern.

Method Summary

Modifier and Type	Method and Description
private static final void	add(final SortedSet<Integer> vals, final int start, final int end, final int increment)
public CronTrigger	Returns: this instance. daysOfMonth(final int... one or more day numbers ranging from 1 to 31. d) Configure the day-of-month cron field, overwriting any previous value for day-of-month.
public CronTrigger	Returns: this instance. daysOfMonth(final String dayOfMonth cron field. For example, `15,L`. d) Configure the day-of-month cron field, overwriting any previous value for day-of-month.
public CronTrigger	Returns: this instance. daysOfWeek(final DayOfWeek... one or more days of the week. d) Configure the day-of-week cron field, overwriting any previous value for day-of-week.
public CronTrigger	Returns: this instance. daysOfWeek(final String dayOfWeek cron field. For example, `MON-FRI,SAT#L`. d) Configure the day-of-week cron field, overwriting any previous value for day-of-week.
public ZonedDateTime	Returns: the date/time after which the next execution of the task should start. getNextRunTime(final LastExecution information about the last execution of the task. This value will be null if the task has not yet run. lastExecutionInfo, final ZonedDateTime the date/time at which the `ManagedScheduledExecutorService.schedule` method was invoked to schedule the task. taskScheduledTime) Implements jakarta.enterprise.concurrent.ZonedTrigger.getNextRunTime. 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.
public final ZoneId	Returns: timezone to use for operations on this trigger. getZoneId() Overrides default jakarta.enterprise.concurrent.ZonedTrigger.getZoneId. Returns the timezone to use for `ZonedDateTime` that is supplied to the `getNextRunTime` and `skipRun` methods.
public CronTrigger	Returns: this instance. hours(final int... one or more hour values ranging from 0 to 23. h) Configure the hours cron field, overwriting any previous value for hours.
public CronTrigger	Returns: this instance. hours(final String hours cron field. For example, `9-17` for 9am to 5pm. h) Configure the hours cron field, overwriting any previous value for hours.
public CronTrigger	Returns: this instance. minutes(final int... one or more minute values ranging from 0 to 59. m) Configure the minutes cron field, overwriting any previous value for minutes.
public CronTrigger	Returns: this instance. minutes(final String minutes cron field. For example, `5/10` for 10 minute intervals starting at 5 minutes after the hour (:05, :15, :25, :35, :45, :55). m) Configure the minutes cron field, overwriting any previous value for minutes.
public CronTrigger	Returns: this instance. months(final Month... one or more months. m) Configure the month cron field, overwriting any previous value for month.
public CronTrigger	Returns: this instance. months(final String months cron field. For example, `SEP-NOV,FEB-MAY`. m) Configure the months cron field, overwriting any previous value for months.
protected ZonedDateTime	Returns: next date/time according to the cron schedule, or the original time if it matches. next(final ZonedDateTime the date/time from which to compute the next time. from) Advance to the next date/time according to the cron schedule.
private ZonedDateTime	Returns: ZonedDateTime for next month nextDayOfMonth(final int index of the day in daysOfMonth[] dayIndex, final int index of the last day of the month in daysOfMonth[] lastDayIndex, final int index of the month in months[] monthIndex, final int year year, final ZonedDateTime Date/Time time) Advance to next day of month.
private ZonedDateTime	Returns: ZonedDateTime for next hour nextHour(final int index of the hour in hours[] hourIndex, final int index of the day in daysOfMonth[] dayIndex, final int index of the last day of the month in daysOfMonth[] lastDayIndex, final int day of month dayOfMonth, final int index of the month in months[] monthIndex, final int year year, final ZonedDateTime Date/Time time) Advance to next hour.
private ZonedDateTime	Returns: ZonedDateTime for next second nextMinute(final int index of the minute in minutes[] minuteIndex, final int index of the hour in hours[] hourIndex, final int index of the day in daysOfMonth[] dayIndex, final int index of the last day of the month in daysOfMonth[] lastDayIndex, final int day of month dayOfMonth, final int index of the month in months[] monthIndex, final int year year, final ZonedDateTime Date/Time time) Advance to next minute.
private ZonedDateTime	Returns: ZonedDateTime for next month nextMonth(final int the month month, final int the year year) Advance to next month.
private ZonedDateTime	Returns: ZonedDateTime for next second nextSecond(final int index of the second in seconds[] secondIndex, final int index of the minute in minutes[] minuteIndex, final int index of the hour in hours[] hourIndex, final int index of the day in daysOfMonth[] dayIndex, final int index of the last day of the month in daysOfMonth[] lastDayIndex, final int day of month dayOfMonth, final int index of the month in months[] monthIndex, final int year year, final ZonedDateTime Date/Time time) Advance to next second.
private int[]	Returns: sorted list of values with any duplicates removed. parse(final String cron field type, such as months or hours. type, final int minimum allowed value min, final int maximum allowed value max, final int[] supplied list of values list) Validate that the supplied list values are within the allowed range for the cron field type.
private int[]	Returns: sorted list of values with any duplicates removed. parse(final String cron field type, such as months or hours. name, final int minimum allowed normal value min, final int maximum allowed normal value max, final int maximum allowed special value (L or SUN#L), or max if no special values allowed for this field. maxExt, final String the field's cron expression field, final Function<String, Integer> parser function, such as Integer::parseInt or CronTrigger::parseMonth parser) Validate that the supplied list values are within the allowed range for the cron field type.
private static int	Returns: integer representation of day of month parseDayOfMonth(final String name of day of month day) Convert dayOfMonth value to 1-31, or negative for days from the end of the month For example, L is the last day (-1) and 2L is the second to last day (-2).
private static int	Returns: integer representation of day of week parseDayOfWeek(final String name of day of the week dayName) Convert dayOfWeek value to 1-49 where first 7 are standard week days, next 35 are ordinal 1st-5th of each day, and final 7 are ordinal last for each day.
private static int	Returns: integer representation of month parseMonth(final String name of month (January) monthName) Convert month value to 1-12.
public CronTrigger	Returns: this instance. seconds(final int... one or more seconds values ranging from 0 to 59. s) Configure the seconds cron field, overwriting any previous value for seconds.
public CronTrigger	Returns: this instance. seconds(final String seconds cron field. For example, `30`. s) Configure the seconds cron field, overwriting any previous value for seconds.
public String	Returns: readable representation of the parsed cron expression. toString() Overrides java.lang.Object.toString. Readable representation of the CronTrigger, which displays fields in list form or with the * character for brevity.
private void	toStringBuilder(final StringBuilder The string builder s, final String The cron expression label, final int[] Cron expression as list list, final int Max value of cron expression max) Utility method for repeated logic in toString.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

ALL_DAYS_OF_MONTH	back to summary
private static final int[] ALL_DAYS_OF_MONTH

ALL_DAYS_OF_WEEK	back to summary
private static final int[] ALL_DAYS_OF_WEEK

ALL_MONTHS	back to summary
private static final int[] ALL_MONTHS

DAYS_OF_WEEK	back to summary
private static final Map<String, Integer> DAYS_OF_WEEK

daysOfMonth	back to summary
private int[] daysOfMonth

daysOfWeek	back to summary
private int[] daysOfWeek

hours	back to summary
private int[] hours

LAST	back to summary
private static final int LAST

minutes	back to summary
private int[] minutes

MONTHS	back to summary
private static final Map<String, Integer> MONTHS

months	back to summary
private int[] months

seconds	back to summary
private int[] seconds

ZERO	back to summary
private static final int[] ZERO

zone	back to summary
private final ZoneId zone

Constructor Detail

CronTrigger back to summary

CronTrigger	back to summary
public CronTrigger(final String cron, final ZoneId zone) Constructor that accepts a cron expression. Parameters cron:String cron expression. zone:ZoneId timezone ID to use for `java.time.ZonedDateTime` that is supplied to `getNextRunTime` and `skipRun` methods. Null indicates to use the system default.

public CronTrigger(final String cron, final ZoneId zone)

Constructor that accepts a cron expression.

Parameters

cron:String: cron expression.
zone:ZoneId: timezone ID to use for java.time.ZonedDateTime that is supplied to getNextRunTime and skipRun methods. Null indicates to use the system default.

CronTrigger back to summary

CronTrigger	back to summary
public CronTrigger(final ZoneId zone) Constructor for the fluent configuration pattern. Seconds, minutes, and hours default to 0. The remaining fields default to *. Parameters zone:ZoneId timezone ID to use for `java.time.ZonedDateTime` that is supplied to `getNextRunTime` and `skipRun` methods. Null indicates to use the system default.

public CronTrigger(final ZoneId zone)

Constructor for the fluent configuration pattern. Seconds, minutes, and hours default to 0. The remaining fields default to *.