io.micronaut.scheduling.cron

Class CronExpression

java.lang.Object

io.micronaut.scheduling.cron.CronExpression

public final class CronExpression
extends Object

This provides cron support for Java 8 using java-time.

Parser for unix-like cron expressions: Cron expressions allow specifying combinations of criteria for time such as: "Each Monday-Friday at 08:00" or "Every last friday of the month at 01:30"

A cron expressions consists of 5 or 6 mandatory fields (seconds may be omitted) separated by space.
These are:

Cron expressions

Field		Allowable values		Special Characters
Seconds (may be omitted)		0-59		, - * /
Minutes		0-59		, - * /
Hours		0-23		, - * /
Day of month		1-31		, - * ? / L W
Month		1-12 or JAN-DEC (note: english abbreviations)		, - * /
Day of week		1-7 or MON-SUN (note: english abbreviations)		, - * ? / L #

'*' Can be used in all fields and means 'for all values'. E.g. "*" in minutes, means 'for all minutes'

'?' Can be used in Day-of-month and Day-of-week fields. Used to signify 'no special value'. It is used when one want to specify something for one of those two fields, but not the other.

'-' Used to specify a time interval. E.g. "10-12" in Hours field means 'for hours 10, 11 and 12'

',' Used to specify multiple values for a field. E.g. "MON,WED,FRI" in Day-of-week field means "for monday, wednesday and friday"

'/' Used to specify increments. E.g. "0/15" in Seconds field means "for seconds 0, 15, 30, ad 45". And "5/15" in seconds field means "for seconds 5, 20, 35, and 50". If '*' s specified before '/' it is the same as saying it starts at 0. For every field there's a list of values that can be turned on or off. For Seconds and Minutes these range from 0-59. For Hours from 0 to 23, For Day-of-month it's 1 to 31, For Months 1 to 12. "/" character helsp turn some of these values back on. Thus "7/6" in Months field specify just Month 7. It doesn't turn on every 6 month following, since cron fields never roll over

'L' Can be used on Day-of-month and Day-of-week fields. It signifies last day of the set of allowed values. In Day-of-month field it's the last day of the month (e.g.. 31 jan, 28 feb (29 in leap years), 31 march, etc.). In Day-of-week field it's Sunday. If there's a prefix, this will be subtracted (5L in Day-of-month means 5 days before last day of Month: 26 jan, 23 feb, etc.)

'W' Can be specified in Day-of-Month field. It specifies closest weekday (monday-friday). Holidays are not accounted for. "15W" in Day-of-Month field means 'closest weekday to 15 i in given month'. If the 15th is a Saturday, it gives Friday. If 15th is a Sunday, the it gives following Monday.

'#' Can be used in Day-of-Week field. For example: "5#3" means 'third friday in month' (day 5 = friday, #3 - the third). If the day does not exist (e.g. "5#5" - 5th friday of month) and there aren't 5 fridays in the month, then it won't match until the next month with 5 fridays.

Case-sensitive No fields are case-sensitive

Dependencies between fields Fields are always evaluated independently, but the expression doesn't match until the constraints of each field are met. Overlap of intervals are not allowed. That is: for Day-of-week field "FRI-MON" is invalid, but "FRI-SUN,MON" is valid

Method Summary

Modifier and Type	Method and Description
static CronExpression	create(String expr) Create object from the String expression.
String	getExpression()
ZonedDateTime	nextTimeAfter(ZonedDateTime afterTime) This will search for the next time within the next 4 years.
ZonedDateTime	nextTimeAfter(ZonedDateTime afterTime, long durationInMillis) This will search for the next time within the next durationInMillis millisecond.
ZonedDateTime	nextTimeAfter(ZonedDateTime afterTime, ZonedDateTime dateTimeBarrier) This will search for the next time within the given dateTimeBarrier.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

create

public static CronExpression create(String expr)

Create object from the String expression.

Parameters:

expr - The cron expression

Returns:

The CronExpression instance

nextTimeAfter

public ZonedDateTime nextTimeAfter(ZonedDateTime afterTime)

This will search for the next time within the next 4 years. If there is no time matching, an InvalidArgumentException will be thrown (it is very likely that the cron expression is invalid, like the February 30th).

Parameters:

afterTime - A date-time with a time-zone in the ISO-8601 calendar system

Returns:

The next time within next 4 years

nextTimeAfter

public ZonedDateTime nextTimeAfter(ZonedDateTime afterTime,
                                   long durationInMillis)

This will search for the next time within the next durationInMillis millisecond. Be aware that the duration is specified in millis, but in fact the limit is checked on a day-to-day basis.

Parameters:

afterTime - A date-time with a time-zone in the ISO-8601 calendar system

durationInMillis - The maximum duration in millis after a given time

Returns:

The next time within given duration

nextTimeAfter

public ZonedDateTime nextTimeAfter(ZonedDateTime afterTime,
                                   ZonedDateTime dateTimeBarrier)

This will search for the next time within the given dateTimeBarrier.

Parameters:

afterTime - A date-time with a time-zone in the ISO-8601 calendar system

dateTimeBarrier - The upper limit or maximum date-time to check for next time

Returns:

The next time within given barrier

getExpression

public String getExpression()

Returns:

The underlying cron expression as string.

Since:

3.1.0 Returns String expression.

toString

public String toString()

Overrides:

toString in class Object