Top Description Fields Constructors Methods
jakarta.enterprise.concurrent

public Class CronTrigger

extends Object
implements ZonedTrigger
Class Inheritance
All Implemented Interfaces
jakarta.enterprise.concurrent.ZonedTrigger, jakarta.enterprise.concurrent.Trigger
Imports
java.time.DateTimeException, .DayOfWeek, .Month, .Year, .ZonedDateTime, .ZoneId, java.util.Arrays, .HashMap, .Map, .SortedSet, .TreeSet, java.util.function.Function

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
minutes0-59, *
hours0-23, *
dayOfMonth0-31, *, L
month1-12, JAN-DEC, January-December, *
dayOfWeekSUN-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;
    }
}
Since
3.0

Field Summary

Modifier and TypeField 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

AccessConstructor 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 TypeMethod 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
nextDayOfMonth(final int d, final int l, final int m, final int year, final ZonedDateTime time)

Advance to next day of month.

private ZonedDateTime
nextHour(final int h, final int d, final int l, final int dayOfMonth, final int m, final int year, final ZonedDateTime time)

Advance to next hour.

private ZonedDateTime
nextMinute(final int min, final int h, final int d, final int l, final int dayOfMonth, final int m, final int year, final ZonedDateTime time)

Advance to next minute.

private ZonedDateTime
nextMonth(final int month, final int year)

Advance to next month.

private ZonedDateTime
nextSecond(final int s, final int min, final int h, final int d, final int l, final int dayOfMonth, final int m, final int year, final ZonedDateTime 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
parseDayOfMonth(final String 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
parseDayOfWeek(final String 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
parseMonth(final String 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 s, final String label, final int[] list, final int max)

Utility method for repeated logic in toString.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

ALL_DAYS_OF_MONTHback to summary
private static final int[] ALL_DAYS_OF_MONTH
ALL_DAYS_OF_WEEKback to summary
private static final int[] ALL_DAYS_OF_WEEK
ALL_MONTHSback to summary
private static final int[] ALL_MONTHS
DAYS_OF_WEEKback to summary
private static final Map<String, Integer> DAYS_OF_WEEK
daysOfMonthback to summary
private int[] daysOfMonth
daysOfWeekback to summary
private int[] daysOfWeek
hoursback to summary
private int[] hours
LASTback to summary
private static final int LAST
minutesback to summary
private int[] minutes
MONTHSback to summary
private static final Map<String, Integer> MONTHS
monthsback to summary
private int[] months
secondsback to summary
private int[] seconds
ZEROback to summary
private static final int[] ZERO
zoneback to summary
private final ZoneId zone

Constructor Detail

CronTriggerback 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.

CronTriggerback 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.

Method Detail

addback to summary
private static final void add(final SortedSet<Integer> vals, final int start, final int end, final int increment)
daysOfMonthback to summary
public CronTrigger daysOfMonth(final int... d)

Configure the day-of-month cron field, overwriting any previous value for day-of-month.

Parameters
d:int[]

one or more day numbers ranging from 1 to 31.

Returns:CronTrigger

this instance.

daysOfMonthback to summary
public CronTrigger daysOfMonth(final String d)

Configure the day-of-month cron field, overwriting any previous value for day-of-month.

Parameters
d:String

dayOfMonth cron field. For example, 15,L.

Returns:CronTrigger

this instance.

daysOfWeekback to summary
public CronTrigger daysOfWeek(final DayOfWeek... d)

Configure the day-of-week cron field, overwriting any previous value for day-of-week.

Parameters
d:DayOfWeek[]

one or more days of the week.

Returns:CronTrigger

this instance.

daysOfWeekback to summary
public CronTrigger daysOfWeek(final String d)

Configure the day-of-week cron field, overwriting any previous value for day-of-week.

Parameters
d:String

dayOfWeek cron field. For example, MON-FRI,SAT#L.

Returns:CronTrigger

this instance.

getNextRunTimeback to summary
public ZonedDateTime getNextRunTime(final LastExecution lastExecutionInfo, final ZonedDateTime 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.

Parameters
lastExecutionInfo:LastExecution

information about the last execution of the task. This value will be null if the task has not yet run.

taskScheduledTime:ZonedDateTime

the date/time at which the ManagedScheduledExecutorService.schedule method was invoked to schedule the task.

Returns:ZonedDateTime

the date/time after which the next execution of the task should start.

Annotations
@Override
Exceptions
DateTimeException:
if a next time cannot be determined from the cron expression.
getZoneIdback to summary
public final ZoneId getZoneId()

Overrides default jakarta.enterprise.concurrent.ZonedTrigger.getZoneId.

Returns the timezone to use for ZonedDateTime that is supplied to the getNextRunTime and skipRun methods.

Returns:ZoneId

timezone to use for operations on this trigger.

Annotations
@Override
hoursback to summary
public CronTrigger hours(final int... h)

Configure the hours cron field, overwriting any previous value for hours.

Parameters
h:int[]

one or more hour values ranging from 0 to 23.

Returns:CronTrigger

this instance.

hoursback to summary
public CronTrigger hours(final String h)

Configure the hours cron field, overwriting any previous value for hours.

Parameters
h:String

hours cron field. For example, 9-17 for 9am to 5pm.

Returns:CronTrigger

this instance.

minutesback to summary
public CronTrigger minutes(final int... m)

Configure the minutes cron field, overwriting any previous value for minutes.

Parameters
m:int[]

one or more minute values ranging from 0 to 59.

Returns:CronTrigger

this instance.

minutesback to summary
public CronTrigger minutes(final String m)

Configure the minutes cron field, overwriting any previous value for minutes.

Parameters
m: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).

Returns:CronTrigger

this instance.

monthsback to summary
public CronTrigger months(final Month... m)

Configure the month cron field, overwriting any previous value for month.

Parameters
m:Month[]

one or more months.

Returns:CronTrigger

this instance.

monthsback to summary
public CronTrigger months(final String m)

Configure the months cron field, overwriting any previous value for months.

Parameters
m:String

months cron field. For example, SEP-NOV,FEB-MAY.

Returns:CronTrigger

this instance.

nextback to summary
protected ZonedDateTime next(final ZonedDateTime from)

Advance to the next date/time according to the cron schedule.

Parameters
from:ZonedDateTime

the date/time from which to compute the next time.

Returns:ZonedDateTime

next date/time according to the cron schedule, or the original time if it matches.

nextDayOfMonthback to summary
private ZonedDateTime nextDayOfMonth(final int d, final int l, final int m, final int year, final ZonedDateTime time)

Advance to next day of month.

nextHourback to summary
private ZonedDateTime nextHour(final int h, final int d, final int l, final int dayOfMonth, final int m, final int year, final ZonedDateTime time)

Advance to next hour.

nextMinuteback to summary
private ZonedDateTime nextMinute(final int min, final int h, final int d, final int l, final int dayOfMonth, final int m, final int year, final ZonedDateTime time)

Advance to next minute.

nextMonthback to summary
private ZonedDateTime nextMonth(final int month, final int year)

Advance to next month.

nextSecondback to summary
private ZonedDateTime nextSecond(final int s, final int min, final int h, final int d, final int l, final int dayOfMonth, final int m, final int year, final ZonedDateTime time)

Advance to next second.

parseback to summary
private int[] parse(final String type, final int min, final int max, final int[] list)

Validate that the supplied list values are within the allowed range for the cron field type.

Parameters
type:String

cron field type, such as months or hours.

min:int

minimum allowed value

max:int

maximum allowed value

list:int[]

supplied list of values

Returns:int[]

sorted list of values with any duplicates removed.

parseback to summary
private int[] parse(final String name, final int min, final int max, final int maxExt, final String field, final Function<String, Integer> parser)

Validate that the supplied list values are within the allowed range for the cron field type.

Parameters
name:String

cron field type, such as months or hours.

min:int

minimum allowed normal value

max:int

maximum allowed normal value

maxExt:int

maximum allowed special value (L or SUN#L), or max if no special values allowed for this field.

field:String

the field's cron expression

parser:Function<String, Integer>

parser function, such as Integer::parseInt or CronTrigger::parseMonth

Returns:int[]

sorted list of values with any duplicates removed.

parseDayOfMonthback to summary
private static int parseDayOfMonth(final String day) throws IllegalArgumentException

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).

parseDayOfWeekback to summary
private static int parseDayOfWeek(final String dayName) throws IllegalArgumentException

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.

parseMonthback to summary
private static int parseMonth(final String monthName) throws IllegalArgumentException

Convert month value to 1-12.

secondsback to summary
public CronTrigger seconds(final int... s)

Configure the seconds cron field, overwriting any previous value for seconds.

Parameters
s:int[]

one or more seconds values ranging from 0 to 59.

Returns:CronTrigger

this instance.

secondsback to summary
public CronTrigger seconds(final String s)

Configure the seconds cron field, overwriting any previous value for seconds.

Parameters
s:String

seconds cron field. For example, 30.

Returns:CronTrigger

this instance.

toStringback to summary
public String toString()

Overrides java.lang.Object.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
Returns:String

readable representation of the parsed cron expression.

Annotations
@Override
toStringBuilderback to summary
private void toStringBuilder(final StringBuilder s, final String label, final int[] list, final int max)

Utility method for repeated logic in toString.