| Oracle® Fusion Applications Developer's Guide for Oracle Enterprise Scheduler 11g Release 1 (11.1.1.5) Part Number E10142-01 |
|
|
View PDF |
| Oracle® Fusion Applications Developer's Guide for Oracle Enterprise Scheduler 11g Release 1 (11.1.1.5) Part Number E10142-01 |
|
|
View PDF |
This chapter describes how to define schedules that can be associated with a job definition. Using a schedule you can specify when a job request runs. You can also define and use schedules to specify 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, 2008. 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.
The Recurrence constructor allows you to create a recurrence as follows:
Using the fields defined in the RecurrenceFields class, such as DAY_OF_MONTH.
Using a recurrence expression compliant with the iCalendar (RFC 2445) specification. For information about using iCalendar RFC 2245 expressions see,
Note:
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 8-1 shows the recurrence fields helper classes available to specify a recurrence pattern.
Table 8-1 Recurrence Field Helper Patterns
| Recurrence Field | Description |
|---|---|
|
|
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 8-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.
Example 8-1 Defining a Recurrence with Weekly Frequency
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 8-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 8-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.
Example 8-2 Defining a Recurrence with Four Hourly Frequency
Recurrence recur2 =
new Recurrence(RecurrenceFields.FREQUENCY.HOURLY, 4, null, null);
recur2.validate();
In Example 8-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 8-3 shows a sample recurrence created using the RecurrenceFields helper class and a monthly frequency.
Example 8-3 Defining a Recurrence with 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 8-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 8-4 shows a sample recurrence created using the RecurrenceFields helper class and a monthly frequency specified with a start date and time.
Example 8-4 Defining a Recurrence with Start Date and Time Specified
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 8-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 Calendar instance 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:
http://www.ietf.org/rfc/rfc2445.txt
Example 8-5 shows a sample recurrence created using an iCalendar expression.
Example 8-5 Defining a Recurrence with an iCalendar String Expression
Recurrence recur5 = new Recurrence("FREQ=YEARLY;INTERVAL=1;BYMONTH=5;BYDAY=2MO;");
recur5.validate();
Note:
The following are not supported through iCalendar expressions:COUNT, UNTIL, BYSETPOS, WKST
You can still directly specify a count on the Recurrence object using the setCount method.
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 8-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 RecurrenceFields.FREQUENCY of 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 WEEKLY, only DAY_OF_WEEK and TIME_OF_DAY are sufficient to define which day the weekly occurrences should happen. With a frequency of YEARLY, MONTH_OF_YEAR, DAY_OF_MONTH (or the WEEK_OF_MONTH and 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 RecurrenceFields class.
Example 8-6 shows an explicit date definition.
Example 8-6 Defining an Explicit Date
ExplicitDate date = new ExplicitDate(RecurrenceFields.YEAR.valueOf(2007), RecurrenceFields.MONTH_OF_YEAR.AUGUST, RecurrenceFields.DAY_OF_MONTH.valueOf(17));
In Example 8-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.
The 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 Recurrence object.
Example 8-7 shows how to create an Exclusion instance using a recurrence.
Example 8-7 Defining Explicit Dates and an Exclusion
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 8-7 defines an individual exclusion. For information about creating a list of Exclusions, see Section 8.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.
Define an ExclusionsDefinition object using the list of exclusions.
Use the Metadata Service addExclusionDefinition() method to persist the ExclusionsDefinition.
Finally, when you want to associate an ExclusionsDefinition with a schedule, you use the schedule addExclusion() method.
Example 8-8 shows how to create an ExclusionDefinition and store the definition to the metadata repository.
Example 8-8 Creating and Storing a List of Exclusions in an ExlusionDefinition
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 8-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 8.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 8.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 8.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 MetadataServiceHandle.
MetadataObjectId scheduleId = m_service.addScheduleDefinition(handle, s1, "HOW_TO_PROD");
Define the date, recurrences and exclusions.
Store the schedule using addScheduleDefinition.
Close the session with a finally block.
Example 8-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.
Example 8-9 Creating a Schedule Recurrence with RecurrenceFields Helpers
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 8-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 getTimeZone()returns a java.util.TimeZone value if the Schedule object has as TimeZone set.
You can use Fusion Applications 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 Service and Jobs" in Oracle Fusion Applications Administrator's Guide.
You can use Fusion Applications 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 Service and Jobs" in Oracle Fusion Applications Administrator's Guide.
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|