com.opensymphony.oscache.util
Class FastCronParser

java.lang.Object
  extended by 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.
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.


Copyright © 2011 OpenSymphony. All Rights Reserved.