Defining and Using Schedules

Introduction to Schedules

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.

Defining a Recurrence

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,

http://www.ietf.org/rfc/rfc2445.txt

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.

How to Define a Recurrence with a Recurrence Fields Helper

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 15-1 shows the recurrence fields helper classes available to specify a recurrence pattern.

Table 15-1 Recurrence Field Helper Patterns

Recurrence Field	Description
`DAY_OF_MONTH`	Defines the day of a month
`DAY_OF_WEEK`	Enumeration of the day of a week
`FREQUENCY`	Defines the repeat frequency of a Recurrence. Choices are: `DAILY`: Indicates every day repetition `HOURLY`: Indicates every hour repetition `MINUTELY`: Indicates every minute repetition `MONTHLY`: Indicates every month repetition `SECONDLY`: Indicates every second repetition `WEEKLY`: Indicates every week repetition `YEARLY`: Indicates every year repetition
`MONTH_OF_YEAR`	Defines the months of the year
`TIME_OF_DAY`	Defines the time of the day
`WEEK_OF_MONTH`	Enumerations for the week of a month
`YEAR`	Encapsulate the value of a year

Example 15-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.

In Example 15-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 15-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.

In Example 15-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 15-3 shows a sample recurrence created using the RecurrenceFields helper class and a monthly frequency.

Example 15-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 15-4 shows a sample recurrence created using the RecurrenceFields helper class and a monthly frequency specified with a start date and time.

Example 15-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.

Example 15-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();

Example 15-2 Defining a Recurrence with Four Hourly Frequency

Recurrence recur2 = 
    new Recurrence(RecurrenceFields.FREQUENCY.HOURLY, 4, null, null);
    recur2.validate();

Example 15-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 15-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();

How to Define a Recurrence with an iCalendar RFC 2445 Specification

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 15-5 shows a sample recurrence created using an iCalendar expression.

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.

Example 15-5 Defining a Recurrence with an iCalendar String Expression

Recurrence recur5 = new Recurrence("FREQ=YEARLY;INTERVAL=1;BYMONTH=5;BYDAY=2MO;");
recur5.validate();

What You Need to Know When You Use a Recurrence Fields Helper

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 15-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 does 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 are 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.

What You Need to Know When You Use an iCalendar Expression

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 are 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 does not generate any occurrences before the start date or after the end date (and if specified, any associated start time or end time).

Defining an Explicit Date

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.

How to Define an Explicit Date

Example 15-6 shows an explicit date definition.

Example 15-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 15-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.

What You Need to Know About Explicit Dates

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.

Defining and Storing Exclusions

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.

How to Define an Exclusion

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 15-7 shows how to create an Exclusion instance using a recurrence.

Example 15-7 defines an individual exclusion. For information about creating a list of Exclusions, see How to Create an Exclusions Definition.

Example 15-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);

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.

Example 15-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);
MetadataServiceHandle handle = m_service.open();
MetadataObjectId exId1 = m_service.addExclusionDefinition(handle,exDef1,
"METADATA_UNITTEST_PROD");

Finally, when you want to associate an ExclusionsDefinition with a schedule, you use the schedule addExclusion() method.

Example 15-8 shows how to create an ExclusionDefinition and store the definition to the metadata repository.

Note in Example 15-8 that the ExclusionsDefinition constructor requires three arguments.

Defining and Storing Schedules

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 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 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 Defining and Storing Exclusions

How to Define and Store a Schedule

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,schedule,"HOW_TO_PROD");
```
Define the date, recurrences and exclusions.
Store the schedule using addScheduleDefinition.
Close the session with a finally block.

What Happens When You Define and Store a Schedule

Example 15-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 15-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.

Example 15-9 Creating a Schedule Recurrence with RecurrenceFields Helpers

Recurrence recur = new Recurrence(RecurrenceFields.FREQUENCY.WEEKLY, 1);
 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 15-10 Storing a Schedule

MetadataServiceHandle handle = null;
boolean abort = true;
try
   {
      handle = m_service.open();
      m_service.addScheduleDefinition(handle, schedule, "HOW_TO_PROD");
      abort = false;
   }
finally
   {
      if (handle != null)
      {
         m_service.close(handle, abort);
      }
   }

What You Need to Know About Handling Time Zones with Schedules

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.

Identifying Job Requests That Use a Particular Schedule

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 Administering Oracle Enterprise Scheduler.

Updating and Deleting Schedules

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 Administering Oracle Enterprise Scheduler.