Package 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.

  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

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:

  • Field Details

  • Constructor Details

    • 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 Details

    • 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<RecurrenceFields.MONTH_OF_YEAR> 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<RecurrenceFields.MONTH_OF_YEAR> 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<RecurrenceFields.WEEK_OF_MONTH> 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<RecurrenceFields.DAY_OF_MONTH> 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<RecurrenceFields.DAY_OF_MONTH> 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<RecurrenceFields.DAY_OF_WEEK> 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.

    • validateNotSupportedRecurString

      public void validateNotSupportedRecurString(String recurExpr) throws NotAllowedException
      Checks if this Recurrence expression represents a valid recurrence pattern which is supported by ESS. Not supported patterns by ESS are Not supported clauses: BYSETPOS, UNTIL, COUNT, WKST More than one of BYDAY, BYMONTHDAY, BYYEARDAY is not supported More than one of BYWEEKNO, BYMONTH is not supported
      Parameters:
      recurExpr - - iCal recurrence expression
      Throws:
      NotAllowedException - - thrown if the recurrence expression is not supported by ESS.

    • toDisplayString

      public String toDisplayString(Locale locale)
      Gets a localized string describing this recurrence.
      Parameters:
      locale -
      Returns:
      String a localized string describing this recurrence.