com.opensymphony.oscache.util
Class FastCronParser

java.lang.Object
  com.opensymphony.oscache.util.FastCronParser

public class FastCronParser
extends Object

Parses cron expressions and determines at what time in the past is the most recent match for the supplied expression.

Version:

$Revision: 340 $

Author:

Chris Miller, $Author: ltorunski $

Field Summary

private String	cronExpression Holds the raw cron expression that this parser is handling.
private static int	DAY_OF_MONTH
private static int	DAY_OF_WEEK
private static int[]	DAYS_IN_MONTH A lookup table holding the number of days in each month (with the obvious exception that February requires special handling).
private static int	HOUR
private long[]	lookup This is the main lookup table that holds a parsed cron expression. each long represents one of the above field types.
private int[]	lookupMax This is based on the contents of the lookup table.
private int[]	lookupMin This is based on the contents of the lookup table.
private static int[]	MAX_VALUE
private static int[]	MIN_VALUE
private static int	MINUTE
private static int	MONTH
private static int	NUMBER_OF_CRON_FIELDS

Constructor Summary

FastCronParser()
Creates a FastCronParser that uses a default cron expression of "* * * * *".

FastCronParser(String cronExpression)
Constructs a new FastCronParser based on the supplied expression.

Method Summary

private void	addToLookup(int start, int end, int field, int interval) Adds a group of valid values to the lookup table for the specified field.
private int	dayOfWeek(int day, int month, int year) Calculate the day of the week.
String	getCronExpression() Retrieves the current cron expression.
private int	getDayOfWeekVal(char ch1, char[] element, int i) Quickly retrieves the day of week value (Sun = 0, ...
private String	getExpressionSetSummary(int field) Converts the internal datastructure that holds a particular cron field into a human-readable list of values of the field's contents.
String	getExpressionSummary() Recreates the original human-readable cron expression based on the internal datastructure values.
private int	getMonthVal(char ch1, char[] element, int i) Quickly retrieves the month value (Jan = 1, ..., Dec = 12) that corresponds to the month name that is specified in the character array.
long	getTimeBefore(long time) Find the most recent time that matches this cron expression.
private ValueSet	getValue(int value, char[] element, int i) Extracts a numerical value from inside a character array.
boolean	hasMoreRecentMatch(long time) Determines whether this cron expression matches a date/time that is more recent than the one supplied.
private boolean	isLeapYear(int year) Indicates if a year is a leap year or not.
private ParseException	makeParseException(String msg, char[] data, int offset) Makes a ParseException.
private int	numberOfDaysInMonth(int month, int year) Retrieves the number of days in the supplied month, taking into account leap years.
private void	parseExpression(String expression) Takes a cron expression as an input parameter, and extracts from it the relevant minutes/hours/days/months that the expression matches.
void	setCronExpression(String cronExpression) Resets the cron expression to the value supplied.
private void	storeExpressionValues(char[] element, int field) Stores the values for the supplied cron element into the specified field.

Methods inherited from class java.lang.Object

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

Field Detail

NUMBER_OF_CRON_FIELDS

private static final int NUMBER_OF_CRON_FIELDS

See Also:

Constant Field Values

MINUTE

private static final int MINUTE

See Also:

Constant Field Values

HOUR

private static final int HOUR

See Also:

Constant Field Values

DAY_OF_MONTH

private static final int DAY_OF_MONTH

See Also:

Constant Field Values

MONTH

private static final int MONTH

See Also:

Constant Field Values

DAY_OF_WEEK

private static final int DAY_OF_WEEK

See Also:

Constant Field Values

MIN_VALUE

private static final int[] MIN_VALUE

MAX_VALUE

private static final int[] MAX_VALUE

DAYS_IN_MONTH

private static final int[] DAYS_IN_MONTH

A lookup table holding the number of days in each month (with the obvious exception that February requires special handling).

cronExpression

private String cronExpression

Holds the raw cron expression that this parser is handling.

lookup

private long[] lookup

This is the main lookup table that holds a parsed cron expression. each long represents one of the above field types. Bits in each long value correspond to one of the possbile field values - eg, for the minute field, bits 0 -> 59 in lookup[MINUTE] map to minutes 0 -> 59 respectively. Bits are set if the corresponding value is enabled. So if the minute field in the cron expression was "0,2-8,50", bits 0, 2, 3, 4, 5, 6, 7, 8 and 50 will be set. If the cron expression is "*", the long value is set to Long.MAX_VALUE.

lookupMax

private int[] lookupMax

This is based on the contents of the lookup table. It holds the highest valid field value for each field type.

lookupMin

private int[] lookupMin

This is based on the contents of the lookup table. It holds the lowest valid field value for each field type.

Constructor Detail

FastCronParser

public FastCronParser()

Creates a FastCronParser that uses a default cron expression of "* * * * *". This will match any time that is supplied.

FastCronParser

public FastCronParser(String cronExpression)
               throws ParseException

Constructs a new FastCronParser based on the supplied expression.

Throws:

ParseException - if the supplied expression is not a valid cron expression.

Method Detail

setCronExpression

public void setCronExpression(String cronExpression)
                       throws ParseException

Resets the cron expression to the value supplied.

Parameters:

cronExpression - the new cron expression.

Throws:

ParseException - if the supplied expression is not a valid cron expression.

getCronExpression

public String getCronExpression()

Retrieves the current cron expression.

Returns:

the current cron expression.

hasMoreRecentMatch

public boolean hasMoreRecentMatch(long time)

Determines whether this cron expression matches a date/time that is more recent than the one supplied.

Parameters:

time - The time to compare the cron expression against.

Returns:

true if the cron expression matches a time that is closer to the current time than the supplied time is, false otherwise.

getTimeBefore

public long getTimeBefore(long time)

Find the most recent time that matches this cron expression. This time will always be in the past, ie a lower value than the supplied time.

Parameters:

time - The time (in milliseconds) that we're using as our upper bound.

Returns:

The time (in milliseconds) when this cron event last occurred.

parseExpression

private void parseExpression(String expression)
                      throws ParseException

Takes a cron expression as an input parameter, and extracts from it the relevant minutes/hours/days/months that the expression matches.

Parameters:

expression - A valid cron expression.

Throws:

ParseException - If the supplied expression could not be parsed.

storeExpressionValues

private void storeExpressionValues(char[] element,
                                   int field)
                            throws ParseException

Stores the values for the supplied cron element into the specified field.

Parameters:

element - The cron element to store. A cron element is a single component of a cron expression. For example, the complete set of elements for the cron expression 30 0,6,12,18 * * * would be {"30", "0", "6", "12", "18", "*", "*", "*"}.

field - The field that this expression belongs to. Valid values are MINUTE, HOUR, DAY_OF_MONTH, MONTH and DAY_OF_WEEK.

Throws:

ParseException - if there was a problem parsing the supplied element.

getValue

private ValueSet getValue(int value,
                          char[] element,
                          int i)

Extracts a numerical value from inside a character array.

Parameters:

value - The value of the first character

element - The character array we're extracting the value from

i - The index into the array of the next character to process

Returns:

the new index and the extracted value

addToLookup

private void addToLookup(int start,
                         int end,
                         int field,
                         int interval)
                  throws ParseException

Adds a group of valid values to the lookup table for the specified field. This method handles ranges that increase in arbitrary step sizes. It is also possible to add a single value by specifying a range with the same start and end values.

Parameters:

start - The starting value for the range. Supplying a value that is less than zero will cause the minimum allowable value for the specified field to be used as the start value.

end - The maximum value that can be added (ie the upper bound). If the step size is greater than one, this maximum value may not necessarily end up being added. Supplying a value that is less than zero will cause the maximum allowable value for the specified field to be used as the upper bound.

field - The field that the values should be added to.

interval - Specifies the step size for the range. Any values less than one will be treated as a single step interval.

Throws:

ParseException

isLeapYear

private boolean isLeapYear(int year)

Indicates if a year is a leap year or not.

Parameters:

year - The year to check

Returns:

true if the year is a leap year, false otherwise.

dayOfWeek

private int dayOfWeek(int day,
                      int month,
                      int year)

Calculate the day of the week. Sunday = 0, Monday = 1, ... , Saturday = 6. The formula used is an optimized version of Zeller's Congruence.

Parameters:

day - The day of the month (1-31)

month - The month (1 - 12)

year - The year

Returns:

numberOfDaysInMonth

private int numberOfDaysInMonth(int month,
                                int year)

Retrieves the number of days in the supplied month, taking into account leap years. If the month value is outside the range MIN_VALUE[MONTH] - MAX_VALUE[MONTH] then the year will be adjusted accordingly and the correct number of days will still be returned.

Parameters:

month - The month of interest.

year - The year we are checking.

Returns:

The number of days in the month.

getDayOfWeekVal

private int getDayOfWeekVal(char ch1,
                            char[] element,
                            int i)
                     throws ParseException

Quickly retrieves the day of week value (Sun = 0, ... Sat = 6) that corresponds to the day name that is specified in the character array. Only the first 3 characters are taken into account; the rest are ignored.

Parameters:

element - The character array

i - The index to start looking at

Returns:

The day of week value

Throws:

ParseException

getMonthVal

private int getMonthVal(char ch1,
                        char[] element,
                        int i)
                 throws ParseException

Quickly retrieves the month value (Jan = 1, ..., Dec = 12) that corresponds to the month name that is specified in the character array. Only the first 3 characters are taken into account; the rest are ignored.

Parameters:

element - The character array

i - The index to start looking at

Returns:

The month value

Throws:

ParseException

getExpressionSummary

public String getExpressionSummary()

Recreates the original human-readable cron expression based on the internal datastructure values.

Returns:

A cron expression that corresponds to the current state of the internal data structure.

getExpressionSetSummary

private String getExpressionSetSummary(int field)

Converts the internal datastructure that holds a particular cron field into a human-readable list of values of the field's contents. For example, if the DAY_OF_WEEK field was submitted that had Sunday and Monday specified, the string 0,1 would be returned.

If the field contains all possible values, * will be returned.

Parameters:

field - The field.

Returns:

A human-readable string representation of the field's contents.

makeParseException

private ParseException makeParseException(String msg,
                                          char[] data,
                                          int offset)

Makes a ParseException. The exception message is constructed by taking the given message parameter and appending the supplied character data to the end of it. for example, if msg == "Invalid character encountered" and data == {'A','g','u','s','t'}, the resultant error message would be "Invalid character encountered [Agust]".

Parameters:

msg - The error message

data - The data that the message

offset - The offset into the data where the error was encountered.

Returns:

a newly created ParseException object.