10 Defining and Using Schedules

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

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 Scheduling Service 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 Scheduling Service 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 Calendar instance cal, and its value is set with the set() method calls.

10.2.2 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 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();

10.2.3 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 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 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 Scheduling Service 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 Scheduling Service 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.

10.2.4 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 Scheduling Service 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).

10.3.1 How to Define an Explicit Date

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.

10.3.2 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 Scheduling Service 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.

10.4.1 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 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".

10.4.2 How to Create an Exclusions Definition

To create a list of exclusions and persist the exclusion dates you do the following:

1. Create a list of exclusions.

2. Define an ExclusionsDefinition object using the list of exclusions.

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

10.5.1 How to Define and Store a Schedule

To define a schedule:

1. Create a schedule by defining an Oracle Enterprise Scheduling Service Schedule object and using the schedule constructor to create a new schedule.

2. 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");
   

3. Define the date, recurrences and exclusions.

4. Store the schedule using addScheduleDefinition.

5. Close the session with a finally block.

10.5.2 What Happens When You Define and Store a Schedule

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.

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);
      }
   }

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