it.sauronsoftware.cron4j
Class SchedulingPattern

java.lang.Object
  extended by it.sauronsoftware.cron4j.SchedulingPattern

public class SchedulingPattern
extends java.lang.Object

A UNIX crontab-like pattern is a string split in five space separated parts. Each part is intented as:

  1. Minutes sub-pattern. During which minutes of the hour should the task been launched? The values range is from 0 to 59.
  2. Hours sub-pattern. During which hours of the day should the task been launched? The values range is from 0 to 23.
  3. Days of month sub-pattern. During which days of the month should the task been launched? The values range is from 0 to 31. The special value L can be used to recognize the last day of month.
  4. Months sub-pattern. During which months of the year should the task been launched? The values range is from 1 (January) to 12 (December), otherwise this sub-pattern allows the aliases "jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov" and "dec".
  5. Days of week sub-pattern. During which days of the week should the task been launched? The values range is from 0 (Sunday) to 6 (Saturday), otherwise this sub-pattern allows the aliases "sun", "mon", "tue", "wed", "thu", "fri" and "sat".

The star wildcard character is also admitted, indicating "every minute of the hour", "every hour of the day", "every day of the month", "every month of the year" and "every day of the week", according to the sub-pattern in which it is used.

Once the scheduler is started, a task will be launched when the five parts in its scheduling pattern will be true at the same time.

Some examples:

5 * * * *
This pattern causes a task to be launched once every hour, at the begin of the fifth minute (00:05, 01:05, 02:05 etc.).

* * * * *
This pattern causes a task to be launched every minute.

* 12 * * Mon
This pattern causes a task to be launched every minute during the 12th hour of Monday.

* 12 16 * Mon
This pattern causes a task to be launched every minute during the 12th hour of Monday, 16th, but only if the day is the 16th of the month.

Every sub-pattern can contain two or more comma separated values.

59 11 * * 1,2,3,4,5
This pattern causes a task to be launched at 11:59AM on Monday, Tuesday, Wednesday, Thursday and Friday.

Values intervals are admitted and defined using the minus character.

59 11 * * 1-5
This pattern is equivalent to the previous one.

The slash character can be used to identify step values within a range. It can be used both in the form */c and a-b/c. The subpattern is matched every c values of the range 0,maxvalue or a-b.

*/5 * * * *
This pattern causes a task to be launched every 5 minutes (0:00, 0:05, 0:10, 0:15 and so on).

3-18/5 * * * *
This pattern causes a task to be launched every 5 minutes starting from the third minute of the hour, up to the 18th (0:03, 0:08, 0:13, 0:18, 1:03, 1:08 and so on).

*/15 9-17 * * *
This pattern causes a task to be launched every 15 minutes between the 9th and 17th hour of the day (9:00, 9:15, 9:30, 9:45 and so on... note that the last execution will be at 17:45).

All the fresh described syntax rules can be used together.

* 12 10-16/2 * *
This pattern causes a task to be launched every minute during the 12th hour of the day, but only if the day is the 10th, the 12th, the 14th or the 16th of the month.

* 12 1-15,17,20-25 * *
This pattern causes a task to be launched every minute during the 12th hour of the day, but the day of the month must be between the 1st and the 15th, the 20th and the 25, or at least it must be the 17th.

Finally cron4j lets you combine more scheduling patterns into one, with the pipe character:

0 5 * * *|8 10 * * *|22 17 * * *
This pattern causes a task to be launched every day at 05:00, 10:08 and 17:22.

Since:
2.0
Author:
Carlo Pelliccia

Field Summary
protected  java.util.ArrayList dayOfMonthMatchers
          The ValueMatcher list for the "day of month" field.
protected  java.util.ArrayList dayOfWeekMatchers
          The ValueMatcher list for the "day of week" field.
protected  java.util.ArrayList hourMatchers
          The ValueMatcher list for the "hour" field.
protected  int matcherSize
          How many matcher groups in this pattern?
protected  java.util.ArrayList minuteMatchers
          The ValueMatcher list for the "minute" field.
protected  java.util.ArrayList monthMatchers
          The ValueMatcher list for the "month" field.
 
Constructor Summary
SchedulingPattern(java.lang.String pattern)
          Builds a SchedulingPattern parsing it from a string.
 
Method Summary
 boolean match(long millis)
          This methods returns true if the given timestamp (expressed as a UNIX-era millis value) matches the pattern, according to the system default time zone.
 boolean match(java.util.TimeZone timezone, long millis)
          This methods returns true if the given timestamp (expressed as a UNIX-era millis value) matches the pattern, according to the given time zone.
 java.lang.String toString()
          Returns the pattern as a string.
static boolean validate(java.lang.String schedulingPattern)
          Validates a string as a scheduling pattern.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

minuteMatchers

protected java.util.ArrayList minuteMatchers
The ValueMatcher list for the "minute" field.


hourMatchers

protected java.util.ArrayList hourMatchers
The ValueMatcher list for the "hour" field.


dayOfMonthMatchers

protected java.util.ArrayList dayOfMonthMatchers
The ValueMatcher list for the "day of month" field.


monthMatchers

protected java.util.ArrayList monthMatchers
The ValueMatcher list for the "month" field.


dayOfWeekMatchers

protected java.util.ArrayList dayOfWeekMatchers
The ValueMatcher list for the "day of week" field.


matcherSize

protected int matcherSize
How many matcher groups in this pattern?

Constructor Detail

SchedulingPattern

public SchedulingPattern(java.lang.String pattern)
                  throws InvalidPatternException
Builds a SchedulingPattern parsing it from a string.

Parameters:
pattern - The pattern as a crontab-like string.
Throws:
InvalidPatternException - If the supplied string is not a valid pattern.
Method Detail

validate

public static boolean validate(java.lang.String schedulingPattern)
Validates a string as a scheduling pattern.

Parameters:
schedulingPattern - The pattern to validate.
Returns:
true if the given string represents a valid scheduling pattern; false otherwise.

match

public boolean match(java.util.TimeZone timezone,
                     long millis)
This methods returns true if the given timestamp (expressed as a UNIX-era millis value) matches the pattern, according to the given time zone.

Parameters:
timezone - A time zone.
millis - The timestamp, as a UNIX-era millis value.
Returns:
true if the given timestamp matches the pattern.

match

public boolean match(long millis)
This methods returns true if the given timestamp (expressed as a UNIX-era millis value) matches the pattern, according to the system default time zone.

Parameters:
millis - The timestamp, as a UNIX-era millis value.
Returns:
true if the given timestamp matches the pattern.

toString

public java.lang.String toString()
Returns the pattern as a string.

Overrides:
toString in class java.lang.Object
Returns:
The pattern as a string.