|
Oracle Fusion Applications Java API Reference for Oracle Enterprise Scheduler Service 11g Release 1 (11.1.1.6) E20742-03 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object oracle.as.scheduler.Recurrence
public class Recurrence
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.
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.
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.
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.
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);
RecurrenceFields
,
ExplicitDate
,
Schedule
,
Exclusion
,
ExclusionsDefinition
,
Serialized FormConstructor 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 |
---|
public Recurrence(java.lang.String iCalExpr)
iCalExpr
- - RFC-2445 compliant iCalendar expression as String.public Recurrence(RecurrenceFields.FREQUENCY frequency, int interval)
frequency
- - the frequency for the new instance.interval
- - the interval (multiplier) for the frequency.public Recurrence(RecurrenceFields.FREQUENCY frequency, int interval, java.util.Calendar start, java.util.Calendar end)
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 |
---|
public void setFrequency(RecurrenceFields.FREQUENCY frequency, int interval) throws UnsupportedOperationException
frequency
- - the new frequency for this object.interval
- - the multiplier for the new frequency.
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public RecurrenceFields.FREQUENCY getFrequency()
public int getInterval()
public void setStartDate(java.util.Calendar date)
date
- - the start date/timepublic java.util.Calendar getStartDate()
public void setEndDate(java.util.Calendar date)
date
- - the end date/time of this object.public java.util.Calendar getEndDate()
public void setRecurExpression(java.lang.String expr) throws UnsupportedOperationException
expr
- - the iCalendar expression to be set for this object.
UnsupportedOperationException
- - thrown if this object
already has frequency and other recurrence fields set.public java.lang.String getRecurExpression()
public void addMonth(RecurrenceFields.MONTH_OF_YEAR month) throws UnsupportedOperationException
month
- - the month to be added to this object.
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public void removeMonth(RecurrenceFields.MONTH_OF_YEAR month) throws UnsupportedOperationException
month
- - the month to be removed from this object.
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public void setMonths(java.util.Collection<RecurrenceFields.MONTH_OF_YEAR> months) throws UnsupportedOperationException
months
- - the months to be set to this object.
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public java.util.Collection<RecurrenceFields.MONTH_OF_YEAR> getMonths()
public void addWeekOfMonth(RecurrenceFields.WEEK_OF_MONTH week) throws UnsupportedOperationException
week
- - the week of month to be added to this object.
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public void removeWeekOfMonth(RecurrenceFields.WEEK_OF_MONTH week) throws UnsupportedOperationException
week
- - the week of month to be removed from this object.
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public java.util.Collection<RecurrenceFields.WEEK_OF_MONTH> getWeeksOfMonth()
public void addDayOfMonth(RecurrenceFields.DAY_OF_MONTH day) throws UnsupportedOperationException
day
- - the day of month to be added to this object.
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public void removeDayOfMonth(RecurrenceFields.DAY_OF_MONTH day) throws UnsupportedOperationException
day
- - the day of month to be removed from this object.
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public void setDaysOfMonth(java.util.Collection<RecurrenceFields.DAY_OF_MONTH> days) throws UnsupportedOperationException
days
- - the days of month to be set for this object.
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public java.util.Collection<RecurrenceFields.DAY_OF_MONTH> getDaysOfMonth()
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public void addDayOfWeek(RecurrenceFields.DAY_OF_WEEK day) throws UnsupportedOperationException
day
- - the day of week to be added to this object.
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public void removeDayOfWeek(RecurrenceFields.DAY_OF_WEEK day) throws UnsupportedOperationException
day
- - the day of week to be removed from this object.
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public java.util.Collection<RecurrenceFields.DAY_OF_WEEK> getDaysOfWeek()
public void setRecurTime(RecurrenceFields.TIME_OF_DAY time) throws UnsupportedOperationException
time
- - the time to be added to this object.
UnsupportedOperationException
- - thrown if this object
already has an iCalendar expression set.public RecurrenceFields.TIME_OF_DAY getRecurTime()
public void setCount(int count)
count
- - the count to be set for this object.public int getCount()
public boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
obj
- - the object to compare with this Recurrence.
public int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object
public void validate() throws ValidationException
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.
ValidationException
- - thrown if the instance is not a
valid instance.public java.lang.String compile()
public java.lang.String toDisplayString(java.util.Locale locale)
locale
-
|
Oracle Fusion Applications Java API Reference for Oracle Enterprise Scheduler Service 11g Release 1 (11.1.1.6) E20742-03 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |