oracle.as.scheduler

Class Recurrence

java.lang.Object

oracle.as.scheduler.Recurrence

All Implemented Interfaces:

Serializable

public class Recurrence
extends Object
implements Serializable

Used to define a recurrence pattern for use by Schedule or Exclusion definition.

The recurrence pattern can be created either by using the fields defined in the RecurrenceFields helper class or by directly using a recurrence expression compliant with the RFC-2445 iCalendar specification. It is not possible to create an instance by using both the mechanisms. RecurrenceFields along with methods in this class provides a user-friendly way to define and retrieve a recurrence pattern.

Additionally the class also contains start date/time, end date/time, and count that can be used optionally in defining a recurrence pattern. These additional fields can be used for both a RecurrenceFields based instance or an iCalendar based instance of Recurrence class.

The behavior the Recurrence class with respect to various fields used to create an instance is described by the following rules.

1. Frequency is always mandatory when defining a recurrence pattern based on recurrence fields.
2. Both the start and end date/time are optional. But if specified, it is guaranteed that the object will not generate any occurrences before the start or after the end time.
3. In general if both start date/time and recurrence fields are used, then the recurrence fields always take precedence. This is explained further by following examples.

   If a start date/time is specified with just the frequency fields from the RecurrenceFields then the start date/time defines the occurrences as per the frequency field starting with the first occurrence on the start date/time itself.

   For example if an start date/time of 01-MAY-2000:09:00:00 is specified with a RecurrenceFields.FREQUENCY of WEEKLY without using other recurrence fields, the occurrences will happen once every week starting exactly on 01-MAY-2000:09:00:00. (08-MAY-2000:09:00:00, 15-MAY-2000:09:00:00 and so on).

   In summary, the start date/time alongwith frequency fields provides a quick way of defining a recurrence pattern.

   However if the start date/time is specified together with additional recurrence fields, the recurrence fields takes precedence and the start date/time (and end date/time) only acts as absolute boundary points.

   For example along with a start date/time of 01-MAY-2000:09:00:00 and a frequency of WEEKLY, if the additional recurrence field DAY_OF_WEEK is also used with a value of WEDNESDAY, the occurrence will happen on every Wednesday starting with the 1st Wednesday that comes after 01-MAY-2000. Thus 01-MAY-2000 being a Tuesday, the first occurrence in this case will happen on 02-MAY-2000:09:00:00 and not on 01-MAY-2000:09:00:00.

   Further if TIME_OF_DAY is also specified as 11:00:00, all the occurrences will happen on 11:00:00 overridding the 09:00:00 time from the start date/time.

4. When the start date/time is not used, recurrence fields must be used such that a recurrence pattern gets completely defined. The class provides a validate method to check if an instance of Recurrence represents a well-defined recurrence pattern.

   For example just specifying a MONTH_OF_YEAR alone does not define a recurrence pattern when no start date/time is present.

   Without start date/time the number of minimum recurrence fields required to define a pattern depends upon the value of the frequency used. For example with frequency of WEEKLY, only DAY_OF_WEEK, and TIME_OF_DAY are required to define which day the weekly occurrences should happen.

   However with a frequency of YEARLY, required fields are MONTH_OF_YEAR, DAY_OF_MONTH (or the WEEK_OF_MONTH and DAY_OF_WEEK) and the TIME_OF_DAY.

5. Multiple values for recurrence fields are supported, except the frequency. However at runtime, the recurrence engine will skip invalid combinations silently.

   For example with MONTH_OF_YEAR as January to June, and DAY_OF_MONTH as 30, the recurrence engine will skip the specified day for February.

Finally with just a frequency, the occurrences will happen based on a timestamp provided at runtime if the Recurrence instance itself neither have either a start date/time nor the TIME_OF_DAY field. Typically timestamps in such cases can be provided during request submission. For example a Recurrence can simple indicate a every 2 hour recurrence, and the start date/time at request submission will decide when exact the occurrences start. Note that in such cases, occurrences for different requests can happen on different time but will be 2 hours apart.

Example - Creating a simple hourly Recurrence

In examples like this, the schedule becomes active at whatever start time specified at runtime.

 Recurrence recur = new Recurrence(RecurrenceFields.FREQUENCY.HOURLY, 1);
 

Example - Creating a recurrence for monthly on 2nd Tuesday at 11:00 AM.

This example creates the recurrence without a start date/time.

 Recurrence recur = new Recurrence(RecurrenceFields.FREQUENCY.MONTHLY, 1);
 recur.addWeekOfMonth(RecurrenceFields.WEEK_OF_MONTH.SECOND);
 recur.addDayOfWeek(RecurrenceFields.DAY_OF_WEEK.TUESDAY);
 recur.setRecurTime(RecurrenceFields.TIME_OF_DAY.valueOf(11, 00, 00));
 recur.validate();
 

Example - Creating a schedule to repeat every Friday at 9:00 AM

This example uses the start date/time, where the start date must be a Friday. Note that if the start date does not reflect a Friday, the recurrence will be occur on whatever day the start date represent.

 Calendar cal = Calendar.getInstance();
 cal.set(Calendar.YEAR, 2005);
 cal.set(Calendar.MONTH, Calendar.JULY);
 cal.set(Calendar.DAY_OF_MONTH, 1);
 cal.set(Calendar.HOUR, 9);
 cal.set(Calendar.MINUTE, 0);
 cal.set(Calendar.SECOND, 0);

 Recurrence recur = new Recurrence(RecurrenceFields.FREQUENCY.WEEKLY,
                                   1, cal, null);
 

RFC-2445 iCalendar specification restrictions

Certain features of RFC-2445 are not supported.

1. The following clauses are not supported: UNTIL, COUNT, BYSETPOS, WKST.
2. Only one of BYWEEKDAY, BYMONTHDAY, BYYEARDAY can be set in a single expression.

See Also:

RecurrenceFields, ExplicitDate, Schedule, Exclusion, ExclusionsDefinition, Serialized Form

Constructor Summary

Constructors

Constructor and Description
Recurrence(RecurrenceFields.FREQUENCY frequency, int interval) Constructs a new instance with the given frequency.
Recurrence(RecurrenceFields.FREQUENCY frequency, int interval, Calendar start, Calendar end) Constructs a new instance with the given frequency and the start, end date/time.
Recurrence(String iCalExpr) Constructs a new instance with the specified iCalendar expression.

Method Summary

Methods

Modifier and Type	Method and Description
void	addDayOfMonth(RecurrenceFields.DAY_OF_MONTH day) Adds a day of month to this Recurrence objects.
void	addDayOfWeek(RecurrenceFields.DAY_OF_WEEK day) Adds a day of week to this Recurrence objects.
void	addMonth(RecurrenceFields.MONTH_OF_YEAR month) Adds a month to this Recurrence objects.
void	addWeekOfMonth(RecurrenceFields.WEEK_OF_MONTH week) Adds a week of month to this Recurrence objects.
boolean	equals(Object obj) Compares an object for equality with this Recurrence object.
int	getCount() Gets recurrence count of this object.
Collection	getDaysOfMonth() Gets the days of month from this Recurrence objects.
Collection	getDaysOfWeek() Gets the collection of the days of week set in this object.
Calendar	getEndDate() Gets the end date/time of this Recurrence object.
RecurrenceFields.FREQUENCY	getFrequency() Gets the frequency value of this Recurrence object.
int	getInterval() Gets the interval (multiplier) for the frequency of this Recurrence object.
Collection	getMonths() Gets the list of months set for this Recurrence object.
String	getRecurExpression() Gets iCalendar expression of this Recurrence object.
RecurrenceFields.TIME_OF_DAY	getRecurTime() Gets the recurrence time of this object.
Calendar	getStartDate() Gets the start date/time of this Recurrence object.
Collection	getWeeksOfMonth() Retrieves the weeks of the month set in this object.
int	hashCode() The hash code value of this Recurence object.
void	removeDayOfMonth(RecurrenceFields.DAY_OF_MONTH day) Removes a day of month from this Recurrence objects.
void	removeDayOfWeek(RecurrenceFields.DAY_OF_WEEK day) Removes a day of week from this Recurrence objects.
void	removeMonth(RecurrenceFields.MONTH_OF_YEAR month) Removes a month from this Recurrence objects.
void	removeWeekOfMonth(RecurrenceFields.WEEK_OF_MONTH week) Removes a week of month from this Recurrence objects.
void	setCount(int count) Sets the count indicating the maximum number of occurrences this object will generate.
void	setDaysOfMonth(Collection days) Sets days of month from this Recurrence objects.
void	setEndDate(Calendar date) Sets the end date/time of this Recurrence object.
void	setFrequency(RecurrenceFields.FREQUENCY frequency, int interval) Sets the frequency of this Recurrence object.
void	setMonths(Collection months) Sets the list of month of this Recurrence objects.
void	setRecurExpression(String expr) Sets the iCalendar expression of this Recurrence object.
void	setRecurTime(RecurrenceFields.TIME_OF_DAY time) Sets the time of this Recurrence objects.
void	setStartDate(Calendar date) Sets the start date/time for this Recurrence object.
String	toDisplayString(Locale locale) Gets a localized string describing this recurrence.
String	toString() Gets the string representation of this Recurrence object.
void	validate() Checks if this Recurrence instance represents a complete recurrence pattern or not.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Recurrence

public Recurrence(String iCalExpr)

Constructs a new instance with the specified iCalendar expression.

Parameters:

iCalExpr - RFC-2445 compliant iCalendar expression as String.

Recurrence

public Recurrence(RecurrenceFields.FREQUENCY frequency,
          int interval)

Constructs a new instance with the given frequency. Additional methods must be called to define a complete recurrence pattern.

Parameters:

frequency - the frequency for the new instance.

interval - the interval (multiplier) for the frequency.

Recurrence

public Recurrence(RecurrenceFields.FREQUENCY frequency,
          int interval,
          Calendar start,
          Calendar end)

Constructs a new instance with the given frequency and the start, end date/time. The interval gets multiplied to the frequency. For example to get a frequency of every 2nd week, an interval of 2 should be used.

Parameters:

frequency - the frequency for the new instance.

interval - the interval that gets multiplied to the frequency.

start - the start date/time for the recurrence pattern.

end - the end date/time for the recurrence pattern.

Method Detail

setFrequency

public void setFrequency(RecurrenceFields.FREQUENCY frequency,
                int interval)
                  throws UnsupportedOperationException

Sets the frequency of this Recurrence object.

Parameters:

frequency - the new frequency for this object.

interval - the multiplier for the new frequency.

Throws:

UnsupportedOperationException - if this object already has an iCalendar expression set.

getFrequency

public RecurrenceFields.FREQUENCY getFrequency()

Gets the frequency value of this Recurrence object.

Returns:

the frequency enumeration constant of this object.

getInterval

public int getInterval()

Gets the interval (multiplier) for the frequency of this Recurrence object.

Returns:

the interval value of this object.

setStartDate

public void setStartDate(Calendar date)

Sets the start date/time for this Recurrence object. The object only extracts the time up to the seconds. Milliseconds precision is not supported.

Parameters:

date - the start date/time

getStartDate

public Calendar getStartDate()

Gets the start date/time of this Recurrence object.

Returns:

the start date/time of this object.

setEndDate

public void setEndDate(Calendar date)

Sets the end date/time of this Recurrence object.

Parameters:

date - the end date/time of this object.

getEndDate

public Calendar getEndDate()

Gets the end date/time of this Recurrence object.

Returns:

the end date/time of this object.

setRecurExpression

public void setRecurExpression(String expr)
                        throws UnsupportedOperationException

Sets the iCalendar expression of this Recurrence object. A Recurrence object can be created either via the iCalendar expression or by using the fields from RecurrenceFields class, but not both.

Parameters:

expr - the iCalendar expression to be set for this object.

Throws:

UnsupportedOperationException - if this object already has frequency and other recurrence fields set.

getRecurExpression

public String getRecurExpression()

Gets iCalendar expression of this Recurrence object.

Returns:

the String representing iCalendar expression, null if not present.

addMonth

public void addMonth(RecurrenceFields.MONTH_OF_YEAR month)
              throws UnsupportedOperationException

Adds a month to this Recurrence objects. This method cannot be called if this object already has a iCalendar recurrence expression set.

Parameters:

month - the month to be added to this object.

Throws:

UnsupportedOperationException - if this object already has an iCalendar expression set.

removeMonth

public void removeMonth(RecurrenceFields.MONTH_OF_YEAR month)
                 throws UnsupportedOperationException

Removes a month from this Recurrence objects. This method cannot be called if this object already has a iCalendar recurrence expression set.

Parameters:

month - the month to be removed from this object.

Throws:

UnsupportedOperationException - if this object already has an iCalendar expression set.

setMonths

public void setMonths(Collection months)
               throws UnsupportedOperationException

Sets the list of month of this Recurrence objects. This method cannot be called if this object already has a iCalendar recurrence expression set.

Parameters:

months - the collection of RecurrenceFields.MONTH_OF_YEAR months to be set to this object.

Throws:

UnsupportedOperationException - if this object already has an iCalendar expression set.

getMonths

public Collection getMonths()

Gets the list of months set for this Recurrence object.

Returns:

collection of RecurrenceFields.MONTH_OF_YEAR representing the months of this object. If this object does not have months set, {code null} is returned.

addWeekOfMonth

public void addWeekOfMonth(RecurrenceFields.WEEK_OF_MONTH week)
                    throws UnsupportedOperationException

Adds a week of month to this Recurrence objects. This method cannot be called if this object already has a iCalendar recurrence expression set.

Parameters:

week - the week of month to be added to this object.

Throws:

UnsupportedOperationException - if this object already has an iCalendar expression set.

removeWeekOfMonth

public void removeWeekOfMonth(RecurrenceFields.WEEK_OF_MONTH week)
                       throws UnsupportedOperationException

Removes a week of month from this Recurrence objects. This method cannot be called if this object already has a iCalendar recurrence expression set.

Parameters:

week - the week of month to be removed from this object.

Throws:

UnsupportedOperationException - if this object already has an iCalendar expression set.

getWeeksOfMonth

public Collection getWeeksOfMonth()

Retrieves the weeks of the month set in this object.

Returns:

a collection of RecurrenceFields.WEEK_OF_MONTH of this object, or null if not present.

addDayOfMonth

public void addDayOfMonth(RecurrenceFields.DAY_OF_MONTH day)
                   throws UnsupportedOperationException

Adds a day of month to this Recurrence objects. This method cannot be called if this object already has a iCalendar recurrence expression set.

Parameters:

day - the day of month to be added to this object.

Throws:

UnsupportedOperationException - if this object already has an iCalendar expression set.

removeDayOfMonth

public void removeDayOfMonth(RecurrenceFields.DAY_OF_MONTH day)
                      throws UnsupportedOperationException

Removes a day of month from this Recurrence objects. This method cannot be called if this object already has a iCalendar recurrence expression set.

Parameters:

day - the day of month to be removed from this object.

Throws:

UnsupportedOperationException - if this object already has an iCalendar expression set.

setDaysOfMonth

public void setDaysOfMonth(Collection days)
                    throws UnsupportedOperationException

Sets days of month from this Recurrence objects. This method cannot be called if this object already has a iCalendar recurrence expression set.

Parameters:

days - collection of RecurrenceFields.DAY_OF_MONTH representing the days of the month to be set for this object.

Throws:

UnsupportedOperationException - if this object already has an iCalendar expression set.

getDaysOfMonth

public Collection getDaysOfMonth()

Gets the days of month from this Recurrence objects.

Returns:

collection of <RecurrenceFields.DAY_OF_MONTH for the days of month of this object or null if not set.

addDayOfWeek

public void addDayOfWeek(RecurrenceFields.DAY_OF_WEEK day)
                  throws UnsupportedOperationException

Adds a day of week to this Recurrence objects. This method cannot be called if this object already has a iCalendar recurrence expression set.

Parameters:

day - the day of week to be added to this object.

Throws:

UnsupportedOperationException - if this object already has an iCalendar expression set.

removeDayOfWeek

public void removeDayOfWeek(RecurrenceFields.DAY_OF_WEEK day)
                     throws UnsupportedOperationException

Removes a day of week from this Recurrence objects. This method cannot be called if this object already has a iCalendar recurrence expression set.

Parameters:

day - the day of week to be removed from this object.

Throws:

UnsupportedOperationException - if this object already has an iCalendar expression set.

getDaysOfWeek

public Collection getDaysOfWeek()

Gets the collection of the days of week set in this object.

Returns:

a collection of RecurrenceFields.DAY_OF_WEEK indicating the days of week of this object.

setRecurTime

public void setRecurTime(RecurrenceFields.TIME_OF_DAY time)
                  throws UnsupportedOperationException

Sets the time of this Recurrence objects. This method cannot be called if this object already has a iCalendar recurrence expression set.

Parameters:

time - the time to be added to this object.

Throws:

UnsupportedOperationException - if this object already has an iCalendar expression set.

getRecurTime

public RecurrenceFields.TIME_OF_DAY getRecurTime()

Gets the recurrence time of this object.

Returns:

the time of day for this object.

setCount

public void setCount(int count)

Sets the count indicating the maximum number of occurrences this object will generate.

Parameters:

count - the count to be set for this object.

getCount

public int getCount()

Gets recurrence count of this object. The count indicates the maximum number of occurrences this object generates.

Returns:

the count of for this object.

equals

public boolean equals(Object obj)

Compares an object for equality with this Recurrence object.

Overrides:

equals in class Object

Parameters:

obj - the object to compare with this Recurrence.

Returns:

true if the object passed in is an instance of Recurrence and is equal to this Recurrence, false otherwise.

hashCode

public int hashCode()

The hash code value of this Recurence object.

Overrides:

hashCode in class Object

Returns:

the hash code value of this Recurrence object.

toString

public String toString()

Gets the string representation of this Recurrence object. The string representation follows the RFC-2445 format.

Overrides:

toString in class Object

Returns:

the String representation of this Recurrence object.

validate

public void validate()
              throws ValidationException

Checks if this Recurrence instance represents a complete recurrence pattern or not. An instance is considered as complete if it has minimum required fields that can generate occurrences. If an instance does not define any recurrence pattern, it is not a useful instance.

The number of minimum required fields depends on the fields values being specified such as the frequency. Some basic validations are done based on the Gregorian Calendar system. For example, Feb 30th every year is not a valid combination. On the other hand, Feb 29th every year is valid but the effective recurrence is every leap year.

This method does not report any other invalid combinations that the recurrence engine is able to skip at runtime. For example, if for an every month frequency with days of month as 29, 30, and 31, this method will not report any errors indicating the 30, 31 is not a valid day of February or 31 is not a valid day for some of the months. The recurrence engine automatically skips such days.

Throws:

ValidationException - if the instance is not a valid instance.

toDisplayString

public String toDisplayString(Locale locale)

Gets a localized string describing this recurrence.

Parameters:

locale -

Returns:

String a localized string describing this recurrence.