This chapter describes how to define schedules that you can associate with a Oracle Enterprise Scheduler job definition, specifying when a job request runs and including administrative actions such as workshifts that specify time-based controls for processing with Oracle Enterprise Scheduler.
This chapter includes the following sections:
Using Oracle Enterprise Scheduler you can create a schedule to determine when a job request runs or use a schedule for other purposes, such as determining when a work assignment becomes active. A schedule can contain a list of explicit dates, such as July 14, 2012. A schedule can also include expressions that represent a set of recurring dates (or times and dates).
Using Oracle Enterprise Scheduler you create a schedule with one or more of the following:
Explicit Date: Defines a date for use in a schedule or exclusion.
Recurrence: Contains an expression that represents a pattern for a recurring date and time. For example, you can specify a recurrence representing a regular period such as Mondays at 10:00AM.
Exclusion: Contains a list of dates to exclude or dates and times to exclude from a schedule. For example, you can create an exclusion that contains a list of holidays to exclude from a schedule.
A recurrence is an expression that represents a recurring date and time. You specify a recurrence using an Oracle Enterprise Scheduler
Recurrence object. You use a
Recurrence object when you create a schedule or with an exclusion to specify a list of dates.
Recurrence constructor allows you to create a recurrence as follows:
Using the fields defined in the
RecurrenceFields class, such as
Using a recurrence expression compliant with the iCalendar (RFC 2445) specification. For information about using iCalendar RFC 2245 expressions see,
When you create a recurrence you can only use one of these two mechanisms for each recurrence instance.
A recurrence can also include the following (these are not required):
Start date: The starting time and date for the recurrence pattern.
End date: The ending time and date for the recurrence pattern.
Count: The count for the recurrence pattern. The count indicates the maximum number of occurrences the object generates. For example, if you specify a recurrence representing a regular period such as Mondays at 10:00AM, and a count of 4, then the recurrence includes only four Mondays.
The start date, end date, and count attributes are valid for either a
RecurrenceFields helper based instance or an iCalendar based instance of a recurrence.
You can validate a recurrence using the recurrence
validate() method that checks if an instance of a
Recurrence object represents a well defined and complete recurrence pattern. A
Recurrence instance is considered complete if it has the minimum required fields that can generate occurrences of dates or dates and times.
You can create a recurrence using a recurrence fields helper. The
RecurrenceFields helper class provides a user-friendly way to specify a recurrence pattern. Table 10-1 shows the recurrence fields helper classes available to specify a recurrence pattern.
Defines the day of a month
Enumeration of the day of a week
Defines the repeat frequency of a Recurrence. Choices are:
Defines the months of the year
Defines the time of the day
Enumerations for the week of a month
Encapsulate the value of a year
Example 10-1 shows a sample recurrence created using the
RecurrenceFields helper class with a weekly frequency (every Monday at 10:00 a.m.) using no start or end date.
Recurrence recur1 = new Recurrence(RecurrenceFields.FREQUENCY.WEEKLY, 1, null, null); recur1.addDayOfWeek(RecurrenceFields.DAY_OF_WEEK.MONDAY); recur1.setRecurTime(RecurrenceFields.TIME_OF_DAY.valueOf(10, 0, 0)); recur1.validate();
In Example 10-1, note the following:
The schedule becomes active as specified with the start time supplied at runtime by Oracle Enterprise Scheduler when a job request that uses the schedule is submitted.
The interval parameter 1 specifies that this recurrence generates occurrences every week. You calculate this value by multiplying the frequency with the interval.
Example 10-2 shows a sample recurrence for every 4 hours with no start or end date. The recurrence was created using the
RecurrenceFields helper class with an hourly frequency, an interval multiplier of 4, a null start date, and a null end date.
Recurrence recur2 = new Recurrence(RecurrenceFields.FREQUENCY.HOURLY, 4, null, null); recur2.validate();
In Example 10-2, note the following:
The schedule becomes active as specified with the start time supplied at runtime by Oracle Enterprise Scheduler when a job request that uses the schedule is submitted.
The interval parameter 4 specifies that this recurrence generates occurrences every 4 hours. You calculate this value by multiplying the frequency with the interval.
Example 10-3 shows a sample recurrence created using the
RecurrenceFields helper class and a monthly frequency.
Recurrence recur3 = new Recurrence(RecurrenceFields.FREQUENCY.MONTHLY, 1, null, null); recur3.addWeekOfMonth(RecurrenceFields.WEEK_OF_MONTH.SECOND); recur3.addDayOfWeek(RecurrenceFields.DAY_OF_WEEK.TUESDAY); recur3.setRecurTime(RecurrenceFields.TIME_OF_DAY.valueOf(11, 00, 00)); recur3.validate();
Example 10-3 specifies a recurrence with the following characteristics:
Includes an interval parameter with the value 1 specifies that this recurrence generates occurrences every month.
Includes a specification for the week of month, indicating the second week.
Includes a specification for the day of week, Tuesday.
Includes the specification for the time of day, with the value 11:00.
Example 10-4 shows a sample recurrence created using the
RecurrenceFields helper class and a monthly frequency specified with a start date and time.
Calendar cal = Calendar.getInstance(); cal.set(Calendar.YEAR, 2007); 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 recur4 = new Recurrence(RecurrenceFields.FREQUENCY.WEEKLY, 1, cal, null); recur4.validate();
Example 10-4 defines a recurrence with the following characteristics:
The end date is specified as null meaning no end date.
Using this recurrence, the start date is specified with the
cal, and its value is set with the
set() method calls.
You can specify a recurrence pattern using the
Recurrence constructor with a
String containing an iCalendar (RFC 2445) specification.
For information about using iCalendar RFC 2245 expressions see the following link:
Example 10-5 shows a sample recurrence created using an iCalendar expression.
Recurrence recur5 = new Recurrence("FREQ=YEARLY;INTERVAL=1;BYMONTH=5;BYDAY=2MO;"); recur5.validate();
The following are not supported through iCalendar expressions:
You can still directly specify a count on the
Recurrence object using the
When you define a recurrence with a
RecurrenceFields helper, note the following:
Providing a frequency with one of the
RecurrenceFields.FREQUENCY constants is always mandatory when you define a recurrence pattern using the
RecurrenceFields helper classes (for more information on frequency, see Table 10-1).
The frequency interval supplied with the recurrence constructor is an integer that acts as a multiplier for the supplied frequency. For example if the frequency is
RecurrenceFields.FREQUENCY.HOURLY and the interval is 8, then the combination represents every 8 hours.
Providing either a start or end date is optional. But if a start or end date is specified, it is guaranteed that the object will not generate any occurrences before the start date or after the end date (and if specified, any associated start time or end time).
In general if both start date and recurrence fields are used, then the recurrence fields always take precedence. This qualification means the following:
If a start date is specified with just the frequency fields from the
RecurrenceFields then the start date defines the occurrences with the frequency field, starting with the first occurrence on the start date itself. For example if a start date is specified as 01-MAY-2007:09:00:00 with a
WEEKLY without using other recurrence fields, the occurrences happen once every week starting on 01-MAY-2007:09:00:00 (and including 08-MAY-2007:09:00:00, 15-MAY-2007:09:00:00, and so on).
Thus, providing a start date along with a specification of frequency fields provides a quick way of defining a recurrence pattern.
If the start date or end date is specified together with additional recurrence fields, the recurrence fields take precedence, and the start date or end date only act as absolute boundary points. For example, with a start date of 01-MAY-2007:09:00:00 and a frequency of
WEEKLY if the additional recurrence field
DAY_OF_WEEK is used with a value of
WEDNESDAY the occurrence happens on every Wednesday starting with the first Wednesday that comes after 01-MAY-2007. Because 01-MAY-2007 is a Tuesday, the first occurrence happens on 02-MAY-2007:09:00:00 and not on 01-MAY-2007:09:00:00.
In this case, with the start date of 01-MAY-2007:09:00:00, if the
TIME_OF_DAY is also specified as 11:00:00, all the occurrences happen at 11:00:00 overriding the 09:00:00 time from the starting date specification.
When just a frequency is supplied and a recurrence does not include either a start date, start time, or a
TIME_OF_DAY field, the occurrences happen based on a timestamp that Oracle Enterprise Scheduler supplies at runtime (typically this timestamp is provided during request submission).
For example, when a recurrence indicates a 2 hour recurrence then the time of the job request submission determines the start time for the occurrences. Thus, in such cases the occurrences for a job request are each 2 hours apart, but when multiple job requests are submitted, the start times will be different and are set at the request submission time for the job requests.
When the start date is not used, recurrence fields can be included such that a recurrence pattern is completely defined. For example, specifying a
MONTH_OF_YEAR alone does not define a recurrence pattern when a start date is not also present. Without a start date the number of minimum recurrence fields required to define a pattern depends upon the value of the frequency used. For example with frequency of
TIME_OF_DAY are sufficient to define which day the weekly occurrences should happen. With a frequency of
DAY_OF_MONTH (or the
DAY_OF_WEEK) and the
TIME_OF_DAY are sufficient to define the recurrence pattern.
You can supply multiple values for recurrence fields, except for the frequency field. However, at runtime Oracle Enterprise Scheduler skips invalid combinations silently. For example with
MONTH_OF_YEAR specified as January and ending in June, and with
DAY_OF_MONTH as 30, the recurrence skips an invalid day, that is day 30 for February.
When you define a recurrence with an iCalendar expression, note the following:
When the recurrence does not include either a start date or time and the iCalendar expression does not specify a time of day, the occurrences happen based on a timestamp that Oracle Enterprise Scheduler supplies at runtime (typically this timestamp is provided during request submission).
For example a recurrence can indicate a 2 hour recurrence, and the start date and time of the job request submission determines the exact start time for the occurrences. Note that in such cases, when the start time is not specified, occurrences for different job requests can happen at different times, based on the submission time, but the individual occurrences will be 2 hours apart.
Providing either a start date with
setStartDate() or an end date with
setEndDate() is optional. But if a start or end date is specified, it is guaranteed that the object will not generate any occurrences before the start date or after the end date (and if specified, any associated start time or end time).
An explicit date defines a date and time for use in a schedule or an exclusion. You construct an
ExplicitDate using appropriate fields from the
Example 10-6 shows an explicit date definition.
ExplicitDate date = new ExplicitDate(RecurrenceFields.YEAR.valueOf(2007), RecurrenceFields.MONTH_OF_YEAR.AUGUST, RecurrenceFields.DAY_OF_MONTH.valueOf(17));
In Example 10-6 a
RecurrenceFields helper defines a date in the constructor and the value does not include a time of day. You can optionally use
setTime to set the time associated with an explicit date.
ExplicitDate class provides the ability to define a partial date, when compared with
java.util.Calendar where the time part is not specified. Also all other
java.util.Calendar fields such as
TimeZone are not defined with an
ExplicitDate. When the time part is not specified in an
ExplicitDate, Oracle Enterprise Scheduler computes the time appropriately. For example, consider a schedule that indicates every Monday after June 1, 2007, and adds an explicit date for the 17th of August 2007 (a Friday). In this example, the 17th of August 2007 is a partial date since it does not include a time.
Using an Oracle Enterprise Scheduler exclusion you can represent dates that need to be excluded from a schedule. For example, you can use an exclusion to create a list of holidays to skip in a schedule.
You represent an individual exclusion with an
Exclusion object. You can define the dates to exclude in an exclusion using either an
ExplicitDate or with a
Example 10-7 shows how to create an
Exclusion instance using a recurrence.
Recurrence recur = new Recurrence(RecurrenceFields.FREQUENCY.YEARLY, 1); recur.addMonth(RecurrenceFields.MONTH_OF_YEAR.JULY); recur.addDayOfMonth(RecurrenceFields.DAY_OF_MONTH.valueOf(4)); Exclusion e = new Exclusion("Independence Day", recur);
Example 10-7 defines an individual exclusion. For information about creating a list of Exclusions, see Section 10.4.2, "How to Create an Exclusions Definition".
To create a list of exclusions and persist the exclusion dates you do the following:
Create a list of exclusions.
ExclusionsDefinition object using the list of exclusions.
Use the Metadata Service
addExclusionDefinition() method to persist the
Finally, when you want to associate an
ExclusionsDefinition with a schedule, you use the schedule
Example 10-8 shows how to create an
ExclusionDefinition and store the definition to the metadata repository.
Collection<Exclusion> exclusions = new ArrayList<Exclusion>(); Exclusion e = new Exclusion("Independence Day", recur); exclusions.add(e); ExclusionsDefinition exDef1 = new ExclusionsDefinition("OrclHolidays1", "Annual Holidays", exclusions); MetadataObjectId exId1 = m_service.addExclusionDefinition(handle, exDef1, "METADATA_UNITTEST_PROD");
Note in Example 10-8 that the
ExclusionsDefinition constructor needs three arguments.
Using Oracle Enterprise Scheduler you can create a schedule to determine when a job request runs or use the schedule for other purposes (such as determining when a work assignment becomes active). A schedule contains a list of explicit dates, such as June 13, 2007 or a set of expressions that represent a recurring date or date and time. A schedule can also specify specific exclusion and inclusion dates.
You create a schedule using the following:
Explicit Dates: Define a date for use in a schedule or exclusion. For more information, see Section 10.3, "Defining an Explicit Date"
Recurrences: Contain an expression that represents a pattern for a recurring date and time. For example, you can specify a recurrence representing a regular period such as Mondays at 10:00AM. For more information, see Section 10.2, "Defining a Recurrence"
Exclusions: Contain a list of dates to exclude or dates and times to exclude from a schedule. For example, you can create an exclusion that contains a list of holidays to exclude from a schedule. For more information, see Section 10.4, "Defining and Storing Exclusions"
To define a schedule:
Create a schedule by defining an Oracle Enterprise Scheduler
Schedule object and using the schedule constructor to create a new schedule.
Obtain a metadata service reference,
m_metadataService, and open a metadata session in a
try block with
MetadataObjectId scheduleId = m_service.addScheduleDefinition(handle, s1, "HOW_TO_PROD");
Define the date, recurrences and exclusions.
Store the schedule using
Close the session with a
Example 10-9 shows a sample schedule definition using a recurrence with the
RecurrenceFields helper class for a weekly schedule, specified to run on Mondays at 10:00AM.
The schedule uses the
addInclusionDate() method to add an explicit date to the occurrences in the schedule, and the
addExclusionDate() method to explicitly exclude the date of May 15 from schedule occurrences.
Recurrence recur = new Recurrence(RecurrenceFields.FREQUENCY.WEEKLY); recur.addDayOfWeek(RecurrenceFields.DAY_OF_WEEK.MONDAY); recur.setRecurTime(RecurrenceFields.TIME_OF_DAY.valueOf(10, 0, 0)); ExplicitDate july10 = new ExplicitDate(RecurrenceFields.YEAR.valueOf(2008), RecurrenceFields.MONTH_OF_YEAR.JULY RecurrenceFields.DAY_OF_MONTH.valueOf(10)); ExplicitDate may15 = new ExplicitDate(RecurrenceFields.YEAR.valueOf(2008), RecurrenceFields.MONTH_OF_YEAR.MAY, RecurrenceFields.DAY_OF_MONTH.valueOf(15)); Schedule schedule = new Schedule("everyMonday", "Weekly Schedule", recur); schedule.addInclusionDate(july10); schedule.addExclusionDate(may15);
Example 10-10 shows sample code used to store a schedule. The method
addScheduleDefinition() is used to store the schedule within a
try block, followed by a
finally block that includes error handling.
You can use a
java.util.TimeZone object to set the time zone for a schedule. Use the Schedule
setTimeZone() method to set or clear the
TimeZone for a Schedule. The Schedule method
java.util.TimeZone value if the Schedule object has as
You can use Fusion Middleware Control to search for job requests that use a particular schedule.
For more information about searching for job requests that use a certain schedule, see the section "Searching for Oracle Enterprise Scheduler Job Requests" in the chapter "Managing Oracle Enterprise Scheduler Requests" in Oracle Fusion Middleware Administrator's Guide for Oracle Enterprise Scheduler.
You can use Fusion Middleware Control to edit and delete schedules.
For information about editing and deleting schedules, see the section "Managing Schedules" in the chapter "Managing Oracle Enterprise Scheduler Requests" in Oracle Fusion Middleware Administrator's Guide for Oracle Enterprise Scheduler.