edu.columbia.cpl
Class Recurrence

java.lang.Object
  edu.columbia.cpl.Recurrence

All Implemented Interfaces:

Cloneable

public class Recurrence

extends Object

implements Cloneable

Recurrence represents a recurring interval of time. It corresponds to a CPL time-switch or an iCalendar RRULE.

A recurring interval of time is represented by a start time, a duration (equivalently, an ending time), a frequency, an interval, a termination ("until") date or recurrence count, and a set of by* rules. For more information on this, see below, and the relevant specifications.

Change history:

1.0

Initial version

1.1

Added sub-day by* and intervals, count, and parsers

See Also:

RFC 2445 (iCalendar), RFC 3880 (CPL)

Field Summary

protected DayAndPosition[]	byDay Internal byDay variable.
protected int[]	byHour Internal byHour variable.
protected int[]	byMinute Internal byMinute variable.
protected int[]	byMonth Internal byMonth variable.
protected int[]	byMonthDay Internal byMonthDay variable.
protected int[]	bySecond Internal bySecond variable.
protected int[]	byWeekNo Internal byWeekNo variable.
protected int[]	byYearDay Internal byYearDay variable.
protected int	count Internal count variable.
static int	DAILY The value of frequency indicating a daily recurrence.
protected Calendar	dtStart Internal dtStart variable.
protected Duration	duration Internal duration variable.
protected int	frequency Internal frequency variable.
static int	HOURLY The value of frequency indicating an hourly recurrence.
protected int	interval Internal interval variable.
static long	max_count_loops The maximum number of candidate start times we're willing to consider for count to resolve it to until.
static long	max_count_time The last time we're willing to search for count to resolve it to until.
static int	MINUTELY The value of frequency indicating a minutely recurrence.
static int	MONTHLY The value of frequency indicating a monthly recurrence.
static int	NO_RECURRENCE The value of frequency indicating no recurrence.
static int	SECONDLY The value of frequency indicating a secondly recurrence.
static boolean	strict_count_bounds Whether to throw an exception if a conversion from count to until exceeds its defined bounaries, or simply to assume the count is effectively infinite.
protected Calendar	until Internal until variable.
static int	WEEKLY The value of frequency indicating a weekly recurrence.
static int	YEARLY The value of frequency indicating a yearly recurrence.

Constructor Summary

Recurrence()
Allocate a new Recurrence, with no recurrence frequency, starting at time = 0, duration 0.

Recurrence(Calendar start, Duration dur)
Allocate a new Recurrence, with no recurrence frequency.

Recurrence(Calendar start, Duration dur, int freq)
Allocate a new Recurrence, with the specified frequency.

Method Summary

protected static void	adjust_constant_length_field(int field, Calendar start, Calendar candidate, boolean is_forward) Adjust the time specified by candidate so that the field field equals that of start.
protected static void	adjust_day_of_month(Calendar start, Calendar candidate, boolean is_forward) Adjust the time specified by candidate until its day of the month equals that of start.
protected static void	adjust_day_of_year(Calendar start, Calendar candidate, boolean is_forward) Adjust the time specified by candidate until its day of the year equals that of start.
protected boolean	candidateIsInRecurrence(Calendar candidate, boolean debug) Check whether a particular candidate start time falls within a reptition of the recurrence.
Object	clone() Overrides Cloneable
void	computeUntilFromCount() If count is set and until is not, calculate until from count.
void	computeUntilFromCount(boolean debug) Debugging interface to computeUntilFromCount().
String	generateDateTimeString(Calendar cal) Generate a standard Date-Time string for the given calendar.
String	generateDaySetString(DayAndPosition[] set) Generate a comma-separated DayAndPosition set string (as used in BYDAY arguments).
protected String	generateIntSetString(int[] set) Generate a comma-separated int-set string (as used in BY* arguments).
DayAndPosition[]	getByDay() Get the array of day-of-the-week and position constraints for this recurrence.
String	getByDayString() Get a string representing the day-of-the-week and position constraints for this recurrence.
int[]	getByHour() Get the array of hours-of-the-day constraints for this recurrence.
String	getByHourString() Get a string representing the hours-of-the-day constraints for this recurrence.
int[]	getByMinute() Get the array of minutes-of-the-hour constraints for this recurrence.
String	getByMinuteString() Get a string representing the minutes-of-the-hour constraints for this recurrence.
int[]	getByMonth() Get the array of month constraints for this recurrence.
int[]	getByMonthDay() Get the array of day-of-the-month constraints for this recurrence.
String	getByMonthDayString() Get a string representing the day-of-the-month constraints for this recurrence.
String	getByMonthString() Get a string representing the month constraints for this recurrence.
int[]	getBySecond() Get the array of seconds-of-the-minute constraints for this recurrence.
String	getBySecondString() Get a string representing the seconds-of-the-minute constraints for this recurrence.
int[]	getByWeekNo() Get the array of week-number constraints for this recurrence.
String	getByWeekNoString() Get a string representing the week-number constraints for this recurrence.
int[]	getByYearDay() Get the array of day-of-the-year constraints for this recurrence.
String	getByYearDayString() Get a string representing the day-of-the-year constraints for this recurrence.
Calendar	getCandidateStartTime(Calendar current, boolean is_forward, boolean debug) Get the candidate start time for this recurrence, for a given date.
int	getCount() Get the repeat count of the recurrence.
String	getCountString() Get the repeat count of the recurrence, as a string.
Calendar	getDtEnd() Get the end time of the recurrence.
String	getDtEndString() Get a string representing the end time of the recurrence.
Calendar	getDtStart() Get the start time of the recurrence.
String	getDtStartString() Get a string representation of the start time of the recurrence.
Duration	getDuration() Get the duration of the recurrence.
String	getDurationString() Get the duration of the recurrence, represented as a string.
protected static long	getFieldNumber(Calendar cal, int field) Get the field number corresponding to the date of this calendar (field intervals — seconds, minutes, hours, or days — since the Epoch).
protected static int	getFixedSizeInt(String str, int pos, int ext, String fieldname) Support function for parseDateTime.
int	getFrequency() Get the frequency of the recurrence.
String	getFrequencyString() Get the frequency of the recurrence, as a string.
int	getInterval() Get the interval of the recurrence.
String	getIntervalString() Get the interval of the recurrence, as a string.
protected int	getMinimumInterval() Get the minimum interval for this recurrence, based on the by* parameters and the frequency.
protected static long	getMonthNumber(Calendar cal) Get the month number corresponding to the date of this calendar (months since the Epoch).
protected long	getRecurrenceCount(Calendar candidate) Get the number of instances of the current recurrence frequency that have occured between this recurrence's dtStart, and the time specified by candidate.
Calendar	getUntil() Get the upper bound of the recurrence.
String	getUntilString() Get a string representing the upper bound of the recurrence, or the empty string if unbounded.
protected static long	getWeekNumber(Calendar cal) Get the week number corresponding to the date of this calendar (weeks since the Epoch).
int	getWeekStart() Get the first day of the week for this recurrence.
String	getWeekStartString() Get the first day of the week for this recurrence, as a string.
protected Calendar	internalGetCandidateStartTime(Calendar current, boolean is_forward, boolean debug) Internal version of getCandidateStartTime.
boolean	isInRecurrence(Calendar current) Test if the specified time falls within a repetition of this recurrence.
boolean	isInRecurrence(Calendar current, boolean debug) Debugging interface to isInRecurrence(java.util.Calendar).
protected boolean	matchesByDay(Calendar candidate) Determine if candidate matches the recurrence's byDay rules.
protected static boolean	matchesByField(int[] array, int field, Calendar candidate, boolean allowNegative) Determine if field field of candidate matches an entry in array
protected boolean	matchesByHour(Calendar candidate) Determine if candidate matches the recurrence's byHour rules.
protected boolean	matchesByMinute(Calendar candidate) Determine if candidate matches the recurrence's byMinute rules.
protected boolean	matchesByMonth(Calendar candidate) Determine if candidate matches the recurrence's byMonth rules.
protected boolean	matchesByMonthDay(Calendar candidate) Determine if candidate matches the recurrence's byMonthDay rules.
protected boolean	matchesBySecond(Calendar candidate) Determine if candidate matches the recurrence's bySecond rules.
protected boolean	matchesByWeekNo(Calendar candidate) Determine if candidate matches the recurrence's byWeekNo rules.
protected boolean	matchesByYearDay(Calendar candidate) Determine if candidate matches the recurrence's byYearDay rules.
protected boolean	matchesIndividualByDay(Calendar candidate, DayAndPosition pos) Determine if candidate matches one individual DayAndPosition.
static Calendar	parseDateTime(String str) Parse the given Date-Time string into a Calendar object.
protected DayAndPosition[]	parseDaySet(String str) Parse the given comma-separated list of integers into a DayAndPosition[].
protected static int[]	parseIntSet(String str, String name, int min, int max, boolean neg_ok) Parse the given comma-separated list of integers into a int[].
void	setByDay(DayAndPosition[] b) Set the array of day-of-the-week and position constraints for this recurrence.
void	setByDay(String b) Set the list of day-of-the-week and position constraints for this recurrence.
void	setByHour(int[] b) Set the array of hours-of-the-day constraints for this recurrence.
void	setByHour(String b) Set the list of hours-of-the-day constraints for this recurrence.
void	setByMinute(int[] b) Set the array of minutes-of-the-hour constraints for this recurrence.
void	setByMinute(String b) Set the list of minutes-of-the-hour constraints for this recurrence.
void	setByMonth(int[] b) Set the array of month constraints for this recurrence.
void	setByMonth(String b) Set the list of month constraints for this recurrence.
void	setByMonthDay(int[] b) Set the array of day-of-the-month constraints for this recurrence.
void	setByMonthDay(String b) Set the list of day-of-the-month constraints for this recurrence.
void	setBySecond(int[] b) Set the array of seconds-of-the-minute constraints for this recurrence.
void	setBySecond(String b) Set the list of seconds-of-the-minute constraints for this recurrence.
void	setByWeekNo(int[] b) Set the array of week-number constraints for this recurrence.
void	setByWeekNo(String b) Set the list of week-number constraints for this recurrence.
void	setByYearDay(int[] b) Set the array of day-of-the-year constraints for this recurrence.
void	setByYearDay(String b) Set the list of day-of-the-year constraints for this recurrence.
protected static void	setCalendarWeekStart(Calendar cal, int start) Set the given calendar's week start value to start, and set its minimal days in first week to 4.
void	setCount(int c) Set the repeat count of the recurrence.
void	setCount(String c)
void	setDtEnd(Calendar end) Set the end time of the recurrence.
void	setDtEnd(String end) Set the end time of the recurrence.
void	setDtStart(Calendar start) Set the start time of the recurrence.
void	setDtStart(String start) Set the start time of the recurrence.
void	setDuration(Duration d) Set the duration of the recurrence.
void	setDuration(String str) Set the duration of the recurrence.
void	setFrequency(int freq) Set the frequency of the recurrence.
void	setFrequency(String freq) Set the frequency of the recurrence.
void	setInterval(int intr) Set the interval of the recurrence.
void	setInterval(String intr) Set the interval of the recurrence, from a string.
void	setUntil(Calendar u) Set the upper bound of the recurrence.
void	setUntil(String u) Set the upper bound of a recurrence, based on a string.
void	setWeekStart(int weekstart) Set the first day of the week for this recurrence.
void	setWeekStart(String weekstart) Set the first day of the week for this recurrence.
String	stringizeIntArray(int[] a)
String	toString() Return a string representation of this recurrence.

Methods inherited from class java.lang.Object

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

Field Detail

SECONDLY

public static final int SECONDLY

The value of frequency indicating a secondly recurrence.

See Also:

setFrequency(int), Constant Field Values

MINUTELY

public static final int MINUTELY

The value of frequency indicating a minutely recurrence.

See Also:

setFrequency(int), Constant Field Values

HOURLY

public static final int HOURLY

The value of frequency indicating an hourly recurrence.

See Also:

setFrequency(int), Constant Field Values

DAILY

public static final int DAILY

The value of frequency indicating a daily recurrence.

See Also:

setFrequency(int), Constant Field Values

WEEKLY

public static final int WEEKLY

The value of frequency indicating a weekly recurrence.

See Also:

setFrequency(int), Constant Field Values

MONTHLY

public static final int MONTHLY

The value of frequency indicating a monthly recurrence.

See Also:

setFrequency(int), Constant Field Values

YEARLY

public static final int YEARLY

The value of frequency indicating a yearly recurrence.

See Also:

setFrequency(int), Constant Field Values

NO_RECURRENCE

public static final int NO_RECURRENCE

The value of frequency indicating no recurrence.

See Also:

setFrequency(int), Constant Field Values

dtStart

protected Calendar dtStart

Internal dtStart variable.

See Also:

getDtStart(), setDtStart(java.util.Calendar)

duration

protected Duration duration

Internal duration variable.

See Also:

getDuration(), setDuration(edu.columbia.cpl.Duration)

frequency

protected int frequency

Internal frequency variable.

See Also:

getFrequency(), setFrequency(int)

interval

protected int interval

Internal interval variable.

See Also:

getInterval(), setInterval(int)

until

protected Calendar until

Internal until variable.

See Also:

getUntil(), setUntil(java.util.Calendar)

count

protected int count

Internal count variable.

See Also:

getCount(), setCount(int)

bySecond

protected int[] bySecond

Internal bySecond variable.

See Also:

getBySecond(), setBySecond(int[])

byMinute

protected int[] byMinute

Internal byMinute variable.

See Also:

getByMinute(), setByMinute(int[])

byHour

protected int[] byHour

Internal byHour variable.

See Also:

getByHour(), setByHour(int[])

byDay

protected DayAndPosition[] byDay

Internal byDay variable.

See Also:

getByDay(), setByDay(edu.columbia.cpl.DayAndPosition[])

byMonthDay

protected int[] byMonthDay

Internal byMonthDay variable.

See Also:

getByMonthDay(), setByMonthDay(int[])

byYearDay

protected int[] byYearDay

Internal byYearDay variable.

See Also:

getByYearDay(), setByYearDay(int[])

byWeekNo

protected int[] byWeekNo

Internal byWeekNo variable.

See Also:

getByWeekNo(), setByWeekNo(int[])

byMonth

protected int[] byMonth

Internal byMonth variable.

See Also:

getByMonth(), setByMonth(int[])

max_count_time

public static long max_count_time

The last time we're willing to search for count to resolve it to until. If a recurrence exceeds this instant before it's filled its counts, consider it infinite, or throw an exception, depending on the value of strict_count_bounds.

The default value of this parameter is 2000000000000L, or Wednesday, May 18, 2033 03:33:20.000 UTC. This is comfortably less than time_t (2^31 - 1), so we don't have to worry about rounding on systems which implement java.util.Calendar's support functions on a 32-bit time_t.

See Also:

computeUntilFromCount(), strict_count_bounds

max_count_loops

public static long max_count_loops

The maximum number of candidate start times we're willing to consider for count to resolve it to until. If a recurrence exceeds this instant before it's filled its counts, consider it infinite, or throw an exception, depending on the value of strict_count_bounds.

The default value of this parameter is 10000.

See Also:

computeUntilFromCount(), strict_count_bounds

strict_count_bounds

public static boolean strict_count_bounds

Whether to throw an exception if a conversion from count to until exceeds its defined bounaries, or simply to assume the count is effectively infinite.

The default value of this parameter is false.

See Also:

computeUntilFromCount(), max_count_time, max_count_loops

Constructor Detail

Recurrence

public Recurrence()

Allocate a new Recurrence, with no recurrence frequency, starting at time = 0, duration 0.

Recurrence

public Recurrence(Calendar start,
                  Duration dur)

Allocate a new Recurrence, with no recurrence frequency.

Parameters:

start - The start time, as a broken-down time. (Only the calendar fields are used. Use setWeekStart(int) rather than Calendar.setFirstDayOfWeek(int) to set the first day of the week.)

dur - The duration.

See Also:

setWeekStart(int)

Recurrence

public Recurrence(Calendar start,
                  Duration dur,
                  int freq)

Allocate a new Recurrence, with the specified frequency.

Parameters:

start - The start time, as a broken-down time. (Only the calendar fields are used. Use setWeekStart(int) rather than Calendar.setFirstDayOfWeek(int) to set the first day of the week.)

dur - The duration.

freq - The recurrence frequency (one of DAILY, WEEKLY, MONTHLY, YEARLY, or NO_RECURRENCE).

See Also:

setWeekStart(int)

Method Detail

getDtStart

public Calendar getDtStart()

Get the start time of the recurrence.

Returns:

The start time.

getDtStartString

public String getDtStartString()

Get a string representation of the start time of the recurrence.

Returns:

A string representing the start time.

setDtStart

public void setDtStart(Calendar start)

Set the start time of the recurrence.

Parameters:

start - The start time, as a broken-down time. (Only the calendar fields are used. Use setWeekStart(int) rather than Calendar.setFirstDayOfWeek(int) to set the first day of the week.)

See Also:

setWeekStart(int)

setDtStart

public void setDtStart(String start)

Set the start time of the recurrence.

Parameters:

start - The start time, as a string.

Throws:

IllegalArgumentException - If the given string does not describe a valid Date-Time.

getDuration

public Duration getDuration()

Get the duration of the recurrence.

Returns:

The duration.

getDurationString

public String getDurationString()

Get the duration of the recurrence, represented as a string.

Returns:

A string representing the duration.

setDuration

public void setDuration(Duration d)

Set the duration of the recurrence.

Parameters:

d - The duration.

setDuration

public void setDuration(String str)

Set the duration of the recurrence.

Parameters:

str - A string representing the duration.

Throws:

IllegalArgumentException - If the given string does not describe a valid Duration.

getDtEnd

public Calendar getDtEnd()

Get the end time of the recurrence. The broken-down time of the returned dtEnd will be correct, though its time in milliseconds may not be.

Returns:

The end time.

getDtEndString

public String getDtEndString()

Get a string representing the end time of the recurrence.

Returns:

A string representation of the end time.

setDtEnd

public void setDtEnd(Calendar end)

Set the end time of the recurrence.

Parameters:

end - The end time.

setDtEnd

public void setDtEnd(String end)

Set the end time of the recurrence.

Parameters:

end - The end time, as a string.

Throws:

IllegalArgumentException - If the given string does not describe a valid Date-Time.

getFrequency

public int getFrequency()

Get the frequency of the recurrence.

Returns:

The recurrence frequency (one of SECONDLY, MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY, YEARLY, or NO_RECURRENCE).

getFrequencyString

public String getFrequencyString()

Get the frequency of the recurrence, as a string.

Returns:

A string representing the recurrence frequency (one of "SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY", "MONTHLY", "YEARLY", or null representing no recurrence).

setFrequency

public void setFrequency(int freq)

Set the frequency of the recurrence.

Parameters:

freq - The recurrence frequency (one of SECONDLY, MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY, YEARLY, or NO_RECURRENCE).

Throws:

IllegalArgumentException - if the frequency isn't one of the above values.

setFrequency

public void setFrequency(String freq)

Set the frequency of the recurrence.

Parameters:

freq - A string representing the recurrence frequency (one of "SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY", "MONTHLY", "YEARLY", or "" or null representing no recurrence).

Throws:

IllegalArgumentException - if the frequency isn't one of the above values.

getInterval

public int getInterval()

Get the interval of the recurrence.

Returns:

The recurrence interval.

getIntervalString

public String getIntervalString()

Get the interval of the recurrence, as a string.

Returns:

A string representing the recurrence interval, or null if no interval is defined.

setInterval

public void setInterval(int intr)

Set the interval of the recurrence.

Parameters:

intr - The recurrence interval.

setInterval

public void setInterval(String intr)

Set the interval of the recurrence, from a string.

Parameters:

intr - The recurrence interval, as a string, or null.

Throws:

IllegalArgumentException - if the argument isn't a valid interval.

getUntil

public Calendar getUntil()

Get the upper bound of the recurrence. If count has been set, this computes until from count.

Returns:

The upper bound. null if unbounded.

See Also:

computeUntilFromCount()

getUntilString

public String getUntilString()

Get a string representing the upper bound of the recurrence, or the empty string if unbounded. If count has been set, this computes until from count.

Returns:

A string representation of the upper bound. null if unbounded.

setUntil

public void setUntil(Calendar u)

Set the upper bound of the recurrence.

Parameters:

u - The upper bound, or null if unbounded.

Throws:

IllegalArgumentException - if non-null and count is set.

setUntil

public void setUntil(String u)

Set the upper bound of a recurrence, based on a string.

Parameters:

u - A string representation of the upper bound, or "" or null if unbounded.

Throws:

IllegalArgumentException - if non-""/non-null and count is set.

IllegalArgumentException - If the given string does not describe a valid Date-Time.

getCount

public int getCount()

Get the repeat count of the recurrence.

Returns:

The repeat count. 0 if it is unset; -1 if it is unknown (because 'until' is set).

getCountString

public String getCountString()

Get the repeat count of the recurrence, as a string.

Returns:

A string representation of the repeat count. null if it is unset or unknown (because 'until' is set).

setCount

public void setCount(int c)

Set the repeat count of the recurrence.

Parameters:

c - The repeat count, or 0 if unbounded.

Throws:

IllegalArgumentException - If a non-computed until has been set.

See Also:

computeUntilFromCount()

setCount

public void setCount(String c)

getWeekStart

public int getWeekStart()

Get the first day of the week for this recurrence.

Returns:

The day of the week (one of Calendar.SUNDAY, Calendar.MONDAY, Calendar.TUESDAY, Calendar.WEDNESDAY, Calendar.THURSDAY, Calendar.FRIDAY, or Calendar.SATURDAY).

getWeekStartString

public String getWeekStartString()

Get the first day of the week for this recurrence, as a string.

Returns:

The first day of the week (one of "SU", "MO", "TU", "WE", "TH", "FR", "SA").

setWeekStart

public void setWeekStart(int weekstart)

Set the first day of the week for this recurrence.

Parameters:

weekstart - The day of the week (one of Calendar.SUNDAY, Calendar.MONDAY, Calendar.TUESDAY, Calendar.WEDNESDAY, Calendar.THURSDAY, Calendar.FRIDAY, or Calendar.SATURDAY).

setWeekStart

public void setWeekStart(String weekstart)

Set the first day of the week for this recurrence.

Parameters:

weekstart - The day of the week, as a string (one of "SU", "MO", "TU" "WE", "TH", "FR", "SA").

Throws:

IllegalArgumentException - If the string is not a valid weekday.

getBySecond

public int[] getBySecond()

Get the array of seconds-of-the-minute constraints for this recurrence.

Returns:

The array of seconds of the minute. null if this recurrence has no such constraints.

getBySecondString

public String getBySecondString()

Get a string representing the seconds-of-the-minute constraints for this recurrence.

Returns:

The list of seconds of the minute, comma-separated. null if this recurrence has no such constraints.

setBySecond

public void setBySecond(int[] b)

Set the array of seconds-of-the-minute constraints for this recurrence.

Parameters:

b - The array of seconds of the minute. null if this recurrence has no such constraints.

setBySecond

public void setBySecond(String b)

Set the list of seconds-of-the-minute constraints for this recurrence.

Parameters:

b - The seconds-of-the-minute constraints, as a comma-separated string. null if this recurrence has no such constraints.

Throws:

IllegalArgumentException - If the string is malformed, or if a second is outside the range 0 - 60.

getByMinute

public int[] getByMinute()

Get the array of minutes-of-the-hour constraints for this recurrence.

Returns:

The array of minutes of the hour. null if this recurrence has no such constraints.

getByMinuteString

public String getByMinuteString()

Get a string representing the minutes-of-the-hour constraints for this recurrence.

Returns:

The list of minutes of the hour, comma-separated. null if this recurrence has no such constraints.

setByMinute

public void setByMinute(int[] b)

Set the array of minutes-of-the-hour constraints for this recurrence.

Parameters:

b - The array of minutes of the hour. null if this recurrence has no such constraints.

setByMinute

public void setByMinute(String b)

Set the list of minutes-of-the-hour constraints for this recurrence.

Parameters:

b - The minutes-of-the-hour constraints, as a comma-separated string. null if this recurrence has no such constraints.

Throws:

IllegalArgumentException - If the string is malformed, or if a minute is outside the range 0 - 59.

getByHour

public int[] getByHour()

Get the array of hours-of-the-day constraints for this recurrence.

Returns:

The array of hours of the day. null if this recurrence has no such constraints.

getByHourString

public String getByHourString()

Get a string representing the hours-of-the-day constraints for this recurrence.

Returns:

The list of hours of the day, comma-separated. null if this recurrence has no such constraints.

setByHour

public void setByHour(int[] b)

Set the array of hours-of-the-day constraints for this recurrence.

Parameters:

b - The array of hours of the day. null if this recurrence has no such constraints.

setByHour

public void setByHour(String b)

Set the list of hours-of-the-day constraints for this recurrence.

Parameters:

b - The hours-of-the-day constraints, as a comma-separated string. null if this recurrence has no such constraints.

Throws:

IllegalArgumentException - If the string is malformed, or if an hour is outside the range 0 - 23.

getByDay

public DayAndPosition[] getByDay()

Get the array of day-of-the-week and position constraints for this recurrence.

Returns:

The array of days of the week and positions. null if this recurrence has no such constraints.

getByDayString

public String getByDayString()

Get a string representing the day-of-the-week and position constraints for this recurrence.

Returns:

The list of day-of-the-week and position constraints, comma-separated. null if this recurrence has no such constraints.

setByDay

public void setByDay(DayAndPosition[] b)

Set the array of day-of-the-week and position constraints for this recurrence.

Parameters:

b - The array of days of the week and positions. null if this recurrence has no such constraints.

setByDay

public void setByDay(String b)

Set the list of day-of-the-week and position constraints for this recurrence.

Parameters:

b - The hours-of-the-day constraints, as a comma-separated string. null if this recurrence has no such constraints.

Throws:

IllegalArgumentException - If the string is malformed, or if a day or position is outside its valid range.

getByMonthDay

public int[] getByMonthDay()

Get the array of day-of-the-month constraints for this recurrence.

Returns:

The array of days of the month. null if this recurrence has no such constraints.

getByMonthDayString

public String getByMonthDayString()

Get a string representing the day-of-the-month constraints for this recurrence.

Returns:

The list of days of the month, comma-separated. null if this recurrence has no such constraints.

setByMonthDay

public void setByMonthDay(int[] b)

Set the array of day-of-the-month constraints for this recurrence.

Parameters:

b - The array of days of the month. null if this recurrence has no such constraints.

setByMonthDay

public void setByMonthDay(String b)

Set the list of day-of-the-month constraints for this recurrence.

Parameters:

b - The day-of-the-month constraints, as a comma-separated string. null if this recurrence has no such constraints.

Throws:

IllegalArgumentException - If the string is malformed, or if a day is outside the range 1 - 31 or -31 to -1.

getByYearDay

public int[] getByYearDay()

Get the array of day-of-the-year constraints for this recurrence.

Returns:

The array of days of the year. null if this recurrence has no such constraints.

getByYearDayString

public String getByYearDayString()

Get a string representing the day-of-the-year constraints for this recurrence.

Returns:

The list of days of the year, comma-separated. null if this recurrence has no such constraints.

setByYearDay

public void setByYearDay(int[] b)

Set the array of day-of-the-year constraints for this recurrence.

Parameters:

b - The array of days of the year. null if this recurrence has no such constraints.

setByYearDay

public void setByYearDay(String b)

Set the list of day-of-the-year constraints for this recurrence.

Parameters:

b - The day-of-the-year constraints, as a comma-separated string. null if this recurrence has no such constraints.

Throws:

IllegalArgumentException - If the string is malformed, or if a day is outside the range 1 - 366 or -366 to -1.

getByWeekNo

public int[] getByWeekNo()

Get the array of week-number constraints for this recurrence.

Returns:

The array of week numbers. null if this recurrence has no such constraints.

getByWeekNoString

public String getByWeekNoString()

Get a string representing the week-number constraints for this recurrence.

Returns:

The list of week numbers, comma-separated. null if this recurrence has no such constraints.

setByWeekNo

public void setByWeekNo(int[] b)

Set the array of week-number constraints for this recurrence.

Parameters:

b - The array of week numbers. null if this recurrence has no such constraints.

setByWeekNo

public void setByWeekNo(String b)

Set the list of week-number constraints for this recurrence.

Parameters:

b - The week-number constraints, as a comma-separated string. null if this recurrence has no such constraints.

Throws:

IllegalArgumentException - If the string is malformed, or if a week number is outside the range 1 - 53 or -53 to -1.

getByMonth

public int[] getByMonth()

Get the array of month constraints for this recurrence. Months are specified using the constants from Calendar (Calendar.JANUARY, etc.).

Returns:

The array of months. null if this recurrence has no such constraints.

See Also:

Calendar.JANUARY, Calendar.FEBRUARY, Calendar.MARCH, Calendar.APRIL, Calendar.MAY, Calendar.JUNE, Calendar.JULY, Calendar.AUGUST, Calendar.SEPTEMBER, Calendar.OCTOBER, Calendar.NOVEMBER, Calendar.DECEMBER

getByMonthString

public String getByMonthString()

Get a string representing the month constraints for this recurrence. Months are counted as January = 1.

Returns:

The list of months, comma-separated. null if this recurrence has no such constraints.

setByMonth

public void setByMonth(int[] b)

Set the array of month constraints for this recurrence. Months should be specified using the constants from Calendar (Calendar.JANUARY, etc.).

Parameters:

b - The array of months. null if this recurrence has no such constraints.

See Also:

Calendar.JANUARY, Calendar.FEBRUARY, Calendar.MARCH, Calendar.APRIL, Calendar.MAY, Calendar.JUNE, Calendar.JULY, Calendar.AUGUST, Calendar.SEPTEMBER, Calendar.OCTOBER, Calendar.NOVEMBER, Calendar.DECEMBER

setByMonth

public void setByMonth(String b)

Set the list of month constraints for this recurrence. Months are counted as January = 1.

Parameters:

b - The month constraints, as a comma-separated string. null if this recurrence has no such constraints.

Throws:

IllegalArgumentException - If the string is malformed, or if a month is outside the range 1 - 12.

isInRecurrence

public boolean isInRecurrence(Calendar current)

Test if the specified time falls within a repetition of this recurrence. See algorithm.txt for details of how this works.

Parameters:

current - The "current" time, i.e. the time which is being considered.

Returns:

Whether it falls within a recurrence.

isInRecurrence

public boolean isInRecurrence(Calendar current,
                              boolean debug)

Debugging interface to isInRecurrence(java.util.Calendar).

Parameters:

current - The "current" time, i.e. the time which is being considered.

debug - Whether to print debugging information.

Returns:

Whether it falls within a recurrence.

See Also:

isInRecurrence(java.util.Calendar)

candidateIsInRecurrence

protected boolean candidateIsInRecurrence(Calendar candidate,
                                          boolean debug)

Check whether a particular candidate start time falls within a reptition of the recurrence. Support function for isInRecurrence(java.util.Calendar).

Parameters:

candidate - The candidate start time to be checked.

debug - Whether to print debugging information.

Returns:

whether it falls within a recurrence

getMinimumInterval

protected int getMinimumInterval()

Get the minimum interval for this recurrence, based on the by* parameters and the frequency.

Returns:

One of SECONDLY, MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY, YEARLY, or NO_RECURRENCE (infinite).

getCandidateStartTime

public Calendar getCandidateStartTime(Calendar current,
                                      boolean is_forward,
                                      boolean debug)

Get the candidate start time for this recurrence, for a given date. The candidate start time is the previous/next repitition of the minimum interval, counting from dtStart. See algorithm.txt for more details.

Parameters:

current - The "current" time, i.e. the time which is being considered.

is_forward - Whether to find the next (true) or previous (false) candidate start time.

debug - Whether to print debugging information.

Returns:

The candidate start time, or null if there is none.

internalGetCandidateStartTime

protected Calendar internalGetCandidateStartTime(Calendar current,
                                                 boolean is_forward,
                                                 boolean debug)

Internal version of getCandidateStartTime. Doesn't check various parameters.

Parameters:

current - The "current" time, i.e. the time which is being considered.

is_forward - Whether to find the next (true) or previous (false) candidate start time.

debug - Whether to print debugging information.

Returns:

The candidate start time, or null if there is none.

See Also:

getCandidateStartTime(Calendar, boolean, boolean)

adjust_constant_length_field

protected static void adjust_constant_length_field(int field,
                                                   Calendar start,
                                                   Calendar candidate,
                                                   boolean is_forward)

Adjust the time specified by candidate so that the field field equals that of start. If is_forward, increase the time, otherwise reduce it. Adjust other fields appropriately. Only works for constant-length fields (e.g., Calendar.SECOND, Calendar.MINUTE, Calendar.HOUR_OF_DAY, or Calendar.DAY_OF_WEEK).

Parameters:

field - The calendar field to reduce.

start - The calendar to get the field from

candidate - The calendar to adjust

is_forward - Whether to adjust the time forward.

Throws:

IllegalArgumentException - field is not a constant-length field

adjust_day_of_month

protected static void adjust_day_of_month(Calendar start,
                                          Calendar candidate,
                                          boolean is_forward)

Adjust the time specified by candidate until its day of the month equals that of start. If is_forward, increase the time, otherwise reduce it. Adjust other fields appropriately.

Months can vary in length. The iCal spec says: "If BYxxx rule part values are found which are beyond the available scope (ie, BYMONTHDAY=30 in February), they are simply ignored." Assume this applies to times derived from DTStart as well, and roll back/forward through previous months until we find a match.

Example of how this works: consider the current date October 3, and the start date January 31. Assume !is_forward. start - candidate yields 28, which is more than 0, so we subtract the number of days in the previous month (September), which is 30. The resulting value, 1, of the month day, is not equal to the start month day (31), so we subtract the number of days in the second-previous month (31). This gives us August 31; this agrees, so we stop.

When we roll forward, by contrast, we adjust by the number of days in the current month, not the next month. (What matters is the number of days in the month whose end is being crossed.)

Because there are never two consecutive months with fewer than 31 days, this algorithm will try at most two months (in the Gregorian calendar).

Parameters:

start - The calendar with the target day of the month

candidate - The calendar to adjust

is_forward - Whether to adjust the time forward.

adjust_day_of_year

protected static void adjust_day_of_year(Calendar start,
                                         Calendar candidate,
                                         boolean is_forward)

Adjust the time specified by candidate until its day of the year equals that of start. If is_forward, increase the time, otherwise reduce it. Adjust other fields appropriately.

The day of year is calculated based on (month, day) pairs, not the numeric day of the year (which is different after February in leap years).

For start dates of February 29, this algorithm will loop through at most seven years before it finds a matching year (in the Gregorian calendar). For candidates between 1901 and 2099, it will loop through at most three years. Start dates which do not fall on a leap day will not loop at all.

Parameters:

start - The calendar with the target day of the month

candidate - The calendar to adjust

computeUntilFromCount

public void computeUntilFromCount()

If count is set and until is not, calculate until from count. until will be set to one second after the count'th start time of the interval. If we do not reach count recurrences before we reach max_count_time, or before we have tried max_count_loops candidate start times, set until to max_count_time, or throw an exception, depending on the state of strict_count_bounds.

Throws:

IllegalArgumentException - If we run off the end, and strict_count_bounds is in effect.

See Also:

max_count_time, max_count_loops, strict_count_bounds

computeUntilFromCount

public void computeUntilFromCount(boolean debug)

Debugging interface to computeUntilFromCount().

Throws:

IllegalArgumentException - If we run off the end, and strict_count_bounds is in effect.

See Also:

computeUntilFromCount()

getRecurrenceCount

protected long getRecurrenceCount(Calendar candidate)

Get the number of instances of the current recurrence frequency that have occured between this recurrence's dtStart, and the time specified by candidate.

Parameters:

candidate - The end time of the period

Returns:

The number of recurrences

getFieldNumber

protected static long getFieldNumber(Calendar cal,
                                     int field)

Get the field number corresponding to the date of this calendar (field intervals — seconds, minutes, hours, or days — since the Epoch).

Parameters:

cal - The calendar to calculate.

field - The field to calculate - one of SECONDLY, MINUTELY, HOURLY, or DAILY.

Returns:

The field number.

getWeekNumber

protected static long getWeekNumber(Calendar cal)

Get the week number corresponding to the date of this calendar (weeks since the Epoch). This depends on the calendar's current getWeekStart() setting.

Parameters:

cal - The calendar to calculate.

Returns:

The week number.

See Also:

setWeekStart(int), Calendar.setFirstDayOfWeek(int)

getMonthNumber

protected static long getMonthNumber(Calendar cal)

Get the month number corresponding to the date of this calendar (months since the Epoch).

Parameters:

cal - The calendar to calculate.

Returns:

The month number.

matchesByDay

protected boolean matchesByDay(Calendar candidate)

Determine if candidate matches the recurrence's byDay rules.

Parameters:

candidate - The candidate date to check.

Returns:

Whether it matches.

matchesIndividualByDay

protected boolean matchesIndividualByDay(Calendar candidate,
                                         DayAndPosition pos)

Determine if candidate matches one individual DayAndPosition.

Parameters:

candidate - the candidate date to check

pos - the candidate position

Returns:

whether it matches

matchesByField

protected static boolean matchesByField(int[] array,
                                        int field,
                                        Calendar candidate,
                                        boolean allowNegative)

Determine if field field of candidate matches an entry in array

Parameters:

array - The by* array to check

field - The Calendar field to check

candidate - The Candidate date to check

allowNegative - Whether negative numbers should count as N-from-the-end

Returns:

whether it matches.

matchesBySecond

protected boolean matchesBySecond(Calendar candidate)

Determine if candidate matches the recurrence's bySecond rules.

Parameters:

candidate - the Candidate date to check

Returns:

whether it matches.

matchesByMinute

protected boolean matchesByMinute(Calendar candidate)

Determine if candidate matches the recurrence's byMinute rules.

Parameters:

candidate - the Candidate date to check

Returns:

whether it matches.

matchesByHour

protected boolean matchesByHour(Calendar candidate)

Determine if candidate matches the recurrence's byHour rules.

Parameters:

candidate - the Candidate date to check

Returns:

whether it matches.

matchesByMonthDay

protected boolean matchesByMonthDay(Calendar candidate)

Determine if candidate matches the recurrence's byMonthDay rules.

Parameters:

candidate - the Candidate date to check

Returns:

whether it matches.

matchesByYearDay

protected boolean matchesByYearDay(Calendar candidate)

Determine if candidate matches the recurrence's byYearDay rules.

Parameters:

candidate - the Candidate date to check

Returns:

whether it matches.

matchesByWeekNo

protected boolean matchesByWeekNo(Calendar candidate)

Determine if candidate matches the recurrence's byWeekNo rules.

Parameters:

candidate - the Candidate date to check

Returns:

whether it matches.

matchesByMonth

protected boolean matchesByMonth(Calendar candidate)

Determine if candidate matches the recurrence's byMonth rules.

Parameters:

candidate - the Candidate date to check

Returns:

whether it matches.

setCalendarWeekStart

protected static void setCalendarWeekStart(Calendar cal,
                                           int start)

Set the given calendar's week start value to start, and set its minimal days in first week to 4. Clear its WEEK_OF_MONTH and WEEK_OF_YEAR fields — setting the values doesn't do this, so old values can persist. Note: this works for calendars set by the usual iCalendar/CPL syntax, e.g. those created by parseDateTime(java.lang.String), but can fail if someone actually specified the current time with WEEK_OF_MONTH or WEEK_OF_YEAR.

Parameters:

cal - The calendar to reset

start - The start day of the wee

See Also:

parseDateTime(java.lang.String)

parseDateTime

public static Calendar parseDateTime(String str)

Parse the given Date-Time string into a Calendar object. Internal function used as a support function for set*(String).

The syntax of a Date-Time is given in RFC 2445 as follows:

   date-time  = date "T" time ;As specified in the date and time
                              ;value definitions

   date               = date-value

   date-value         = date-fullyear date-month date-mday
   date-fullyear      = 4DIGIT

   date-month         = 2DIGIT        ;01-12
   date-mday          = 2DIGIT        ;01-28, 01-29, 01-30, 01-31
                                      ;based on month/year

   time               = time-hour time-minute time-second [time-utc]

   time-hour          = 2DIGIT        ;00-23
   time-minute        = 2DIGIT        ;00-59
   time-second        = 2DIGIT        ;00-60
   ;The "60" value is used to account for "leap" seconds.

   time-utc   = "Z"
 

Parameters:

str - The string representation of the date-time.

Returns:

The date-time

Throws:

IllegalArgumentException - If the given string does not describe a valid Date-Time

getFixedSizeInt

protected static int getFixedSizeInt(String str,
                                     int pos,
                                     int ext,
                                     String fieldname)

Support function for parseDateTime. Get a fixed-size integer from the given string. Throw an exception if the string isn't entirely numeric.

Parameters:

str - The string from which to extract the integer

pos - The position of the integer

ext - The extent of the integer

parseIntSet

protected static int[] parseIntSet(String str,
                                   String name,
                                   int min,
                                   int max,
                                   boolean neg_ok)

Parse the given comma-separated list of integers into a int[]. used as a support function for setByXXX(String), other than setByDay(String).

Parameters:

str - The string representation of the integer list.

name - The name of the integer field (for exceptions)

min - The minimum integer value allowed

max - The maximum integer value allowed

neg_ok - Whether negative values are allowed

Returns:

The list of integers

Throws:

IllegalArgumentException - If the given string does not describe a valid list of integers complying with the above requirements

parseDaySet

protected DayAndPosition[] parseDaySet(String str)

Parse the given comma-separated list of integers into a DayAndPosition[]. Used as a support function for setByDay(String).

Parameters:

str - The string representation of the day list.

Returns:

The list of day-and-positions

Throws:

IllegalArgumentException - If the given string does not describe a valid list of day-and-positions

generateDateTimeString

public String generateDateTimeString(Calendar cal)

Generate a standard Date-Time string for the given calendar.

Parameters:

cal - The calendar to generate.

Returns:

A string representation of the calendar.

generateIntSetString

protected String generateIntSetString(int[] set)

Generate a comma-separated int-set string (as used in BY* arguments).

Parameters:

set - A vector of ints

Returns:

A comma-separated list of ints

generateDaySetString

public String generateDaySetString(DayAndPosition[] set)

Generate a comma-separated DayAndPosition set string (as used in BYDAY arguments).

Parameters:

set - A vector of DayAndPositions

Returns:

A comma-separated list of DayAndPositions

clone

public Object clone()

Overrides Cloneable

Returns:

A clone of this object.

toString

public String toString()

Return a string representation of this recurrence. This method is intended to be used only for debugging purposes. The returned string may be empty but may not be null.

Returns:

A string representation of this recurrence.

stringizeIntArray

public String stringizeIntArray(int[] a)