Skip navigation links

oracle.as.scheduler
Class Recurrence

java.lang.Object
oracle.as.scheduler.Recurrence

All Implemented Interfaces:

java.io.Serializable

public class Recurrence

extends java.lang.Object

implements java.io.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 alongwith 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 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 recurrenc fields, the recurrence fields takes precedence and the start date/time (and end date/time) only acts as absolute boundary points.

   For example alongwith 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 start 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.

6. 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 Note that 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);
 

See Also:

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

Constructor Summary

Recurrence(RecurrenceFields.FREQUENCY frequency, int interval)
Constructs a new instance with the given frequency.

Recurrence(RecurrenceFields.FREQUENCY frequency, int interval, java.util.Calendar start, java.util.Calendar end)
Constructs a new instance with the given frequency and the start, end date/time.

Recurrence(java.lang.String iCalExpr)
Constructs a new instance with the specified iCalendar expression.

Method Summary

void	addDayOfMonth(RecurrenceFields.DAY_OF_MONTH day) Method to add a day of month to this Recurrence objects.
void	addDayOfWeek(RecurrenceFields.DAY_OF_WEEK day) Method to add a day of week to this Recurrence objects.
void	addMonth(RecurrenceFields.MONTH_OF_YEAR month) Method to add a month to this Recurrence objects.
void	addWeekOfMonth(RecurrenceFields.WEEK_OF_MONTH week) Method to add a week of month to this Recurrence objects.
java.lang.String	compile() transforms all the recurrence fields used in this object into the equivalent iCalendar expression.
boolean	equals(java.lang.Object obj) Compares an object for equality with this Recurrence object.
int	getCount() Returns the count of this object.
java.util.Collection<RecurrenceFields.DAY_OF_MONTH>	getDaysOfMonth() Method to retrieve the days of month from this Recurrence objects.
java.util.Collection<RecurrenceFields.DAY_OF_WEEK>	getDaysOfWeek() Returns the collection of the days of week set in this object.
java.util.Calendar	getEndDate() Returns the end date/time of this Recurrence object.
RecurrenceFields.FREQUENCY	getFrequency() Returns the frequency value of this Recurrence object.
int	getInterval() Returns the interval (multiplier) for the frequency of this Recurrence object.
java.util.Collection<RecurrenceFields.MONTH_OF_YEAR>	getMonths() Method to return the list of months set for this Recurrence object.
java.lang.String	getRecurExpression() Returns the iCalendar expression of this Recurrence object.
RecurrenceFields.TIME_OF_DAY	getRecurTime() Returns the recurrence time of this object.
java.util.Calendar	getStartDate() Returns the start date/time of this Recurrence object.
java.util.Collection<RecurrenceFields.WEEK_OF_MONTH>	getWeeksOfMonth() Method to retrieve the weeks of the month set in this object.
int	hashCode() Returns the hash code value of this Recurence object.
void	removeDayOfMonth(RecurrenceFields.DAY_OF_MONTH day) Method to remove a day of month from this Recurrence objects.
void	removeDayOfWeek(RecurrenceFields.DAY_OF_WEEK day) Method to remove a day of week from this Recurrence objects.
void	removeMonth(RecurrenceFields.MONTH_OF_YEAR month) Method to remove a month from this Recurrence objects.
void	removeWeekOfMonth(RecurrenceFields.WEEK_OF_MONTH week) Method to remove 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(java.util.Collection<RecurrenceFields.DAY_OF_MONTH> days) Method to set days of month from this Recurrence objects.
void	setEndDate(java.util.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(java.util.Collection<RecurrenceFields.MONTH_OF_YEAR> months) Method to set the list of month of this Recurrence objects.
void	setRecurExpression(java.lang.String expr) Sets the iCalendar expression of this Recurrence object.
void	setRecurTime(RecurrenceFields.TIME_OF_DAY time) Method to set the time of this Recurrence objects.
void	setStartDate(java.util.Calendar date) Method to set the start date/time for this Recurrence object.
java.lang.String	toDisplayString(java.util.Locale locale) Returns a localized string describing this recurrence.
java.lang.String	toString() Returns 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

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Recurrence

public Recurrence(java.lang.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,
                  java.util.Calendar start,
                  java.util.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 - - thrown if this object already has an iCalendar expression set.

getFrequency

public RecurrenceFields.FREQUENCY getFrequency()

Returns the frequency value of this Recurrence object.

Returns:

- the frequency enumeration constant of this object.

getInterval

public int getInterval()

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

Returns:

- the interval value of this object.

setStartDate

public void setStartDate(java.util.Calendar date)

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

Parameters:

date - - the start date/time

getStartDate

public java.util.Calendar getStartDate()

Returns the start date/time of this Recurrence object.

Returns:

- the start date/time of this object.

setEndDate

public void setEndDate(java.util.Calendar date)

Sets the end date/time of this Recurrence object.

Parameters:

date - - the end date/time of this object.

getEndDate

public java.util.Calendar getEndDate()

Returns the end date/time of this Recurrence object.

Returns:

- the end date/time of this object.

setRecurExpression

public void setRecurExpression(java.lang.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 - - thrown if this object already has frequency and other recurrence fields set.

getRecurExpression

public java.lang.String getRecurExpression()

Returns the 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

Method to add 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 - - thrown if this object already has an iCalendar expression set.

removeMonth

public void removeMonth(RecurrenceFields.MONTH_OF_YEAR month)
                 throws UnsupportedOperationException

Method to remove 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 - - thrown if this object already has an iCalendar expression set.

setMonths

public void setMonths(java.util.Collection<RecurrenceFields.MONTH_OF_YEAR> months)
               throws UnsupportedOperationException

Method to set 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 months to be set to this object.

Throws:

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

getMonths

public java.util.Collection<RecurrenceFields.MONTH_OF_YEAR> getMonths()

Method to return the list of months set for this Recurrence object.

Returns:

- collection of enumerations representing the months of this object. If this object does not have months set, null is returned.

addWeekOfMonth

public void addWeekOfMonth(RecurrenceFields.WEEK_OF_MONTH week)
                    throws UnsupportedOperationException

Method to add 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 - - thrown if this object already has an iCalendar expression set.

removeWeekOfMonth

public void removeWeekOfMonth(RecurrenceFields.WEEK_OF_MONTH week)
                       throws UnsupportedOperationException

Method to remove 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 - - thrown if this object already has an iCalendar expression set.

getWeeksOfMonth

public java.util.Collection<RecurrenceFields.WEEK_OF_MONTH> getWeeksOfMonth()

Method to retrieve the weeks of the month set in this object.

Returns:

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

addDayOfMonth

public void addDayOfMonth(RecurrenceFields.DAY_OF_MONTH day)
                   throws UnsupportedOperationException

Method to add 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 - - thrown if this object already has an iCalendar expression set.

removeDayOfMonth

public void removeDayOfMonth(RecurrenceFields.DAY_OF_MONTH day)
                      throws UnsupportedOperationException

Method to remove 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 - - thrown if this object already has an iCalendar expression set.

setDaysOfMonth

public void setDaysOfMonth(java.util.Collection<RecurrenceFields.DAY_OF_MONTH> days)
                    throws UnsupportedOperationException

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

Parameters:

days - - the days of month to be set for this object.

Throws:

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

getDaysOfMonth

public java.util.Collection<RecurrenceFields.DAY_OF_MONTH> getDaysOfMonth()

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

Returns:

- the days of month of this object.

Throws:

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

addDayOfWeek

public void addDayOfWeek(RecurrenceFields.DAY_OF_WEEK day)
                  throws UnsupportedOperationException

Method to add 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 - - thrown if this object already has an iCalendar expression set.

removeDayOfWeek

public void removeDayOfWeek(RecurrenceFields.DAY_OF_WEEK day)
                     throws UnsupportedOperationException

Method to remove 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 - - thrown if this object already has an iCalendar expression set.

getDaysOfWeek

public java.util.Collection<RecurrenceFields.DAY_OF_WEEK> getDaysOfWeek()

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

Returns:

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

setRecurTime

public void setRecurTime(RecurrenceFields.TIME_OF_DAY time)
                  throws UnsupportedOperationException

Method to set 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 - - thrown if this object already has an iCalendar expression set.

getRecurTime

public RecurrenceFields.TIME_OF_DAY getRecurTime()

Returns 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()

Returns the 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(java.lang.Object obj)

Compares an object for equality with this Recurrence object.

Overrides:

equals in class java.lang.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()

Returns the hash code value of this Recurence object.

Overrides:

hashCode in class java.lang.Object

Returns:

- the hash code value of this Recurrence object.

toString

public java.lang.String toString()

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

Overrides:

toString in class java.lang.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 30 is not a valid day for some of the months. The recurrence engine automatically skips such days.

Throws:

ValidationException - - thrown if the instance is not a valid instance.

compile

public java.lang.String compile()

transforms all the recurrence fields used in this object into the equivalent iCalendar expression. If this object is already created with an iCalendar expression, the same expression is returned.

Returns:

- a String containing iCalendar representation of this object.

toDisplayString

public java.lang.String toDisplayString(java.util.Locale locale)

Returns a localized string describing this recurrence.

Parameters:

locale -

Returns:

String a localized string describing this recurrence.

Skip navigation links