oracle.as.scheduler
Class Schedule

java.lang.Object
  oracle.as.scheduler.BaseMetadata<Schedule>
      oracle.as.scheduler.Schedule

All Implemented Interfaces:

java.io.Serializable

public class Schedule
extends BaseMetadata<Schedule>
implements java.io.Serializable

Used to specify time-based recurrence.

The core part of the Schedule is the Recurrence class that provides occurrence based on the defined recurrence pattern. Schedule allows adding dates to be explicitly included for generating occurrences in addition to the one generated by the recurrence pattern.

It is also possible to exclude date/times instances from the list of occurrences a Schedule generates. Such exclusions can be specified in two mode, by explicitly providing a list of dates to an instance of Schedule or by referencing to a named ExclusionsDefinition. An example would be an ExclusionsDefinition that contains the list of holidays for which the Schedule must skip the occurrences if generated.

The start and end date/times if specified in the contained Recurrence only apply to the occurrences generated by the recurrence pattern. Any additional dates explicitly added to the Schedule can fall before the start of after the end date specified.

Schedule provides the ability to mask or allow occurrences that happen to be in the past with respect to the current timestamp at runtime.

Example - Schedule to run every monday at 10:00 am plus on 10th of July 2006, but exclude the 15th May 2006.

 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(2006),
                                      RecurrenceFields.MONTH_OF_YEAR.JULY
                                      RecurrenceFields.DAY_OF_MONTH.valueOf(10));

 ExplicitDate may15 = new ExplicitDate(RecurrenceFields.YEAR.valueOf(2006),
                                      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);
 

See Also:

RecurrenceFields, Recurrence, ExplicitDate, Exclusion, ExclusionsDefinition, Serialized Form

Field Summary

static int

DEFAULT_LIST_LIMIT

Constructor Summary

Schedule(java.lang.String name, java.lang.String description, java.util.Collection<ExplicitDate> dates)
Constructs a new schedule with the given set of explicit dates.

Schedule(java.lang.String name, java.lang.String description, java.util.Collection<ExplicitDate> dates, MetadataObjectId objectId)
Constructs a new schedule with the given set of explicit dates.

Schedule(java.lang.String name, java.lang.String description, Recurrence recur)
Constructs a new instance with the given recurrence.

Schedule(java.lang.String name, java.lang.String description, Recurrence recur, MetadataObjectId objectId)
Constructs a new instance with the given recurrence.

Schedule(java.lang.String name, java.lang.String displayNameKey, java.lang.String descriptionKey, java.util.Collection<ExplicitDate> dates, java.lang.String[] resourceBundleIDs)
Constructs a new schedule with the given set of explicit dates and associate resource bundles.

Schedule(java.lang.String name, java.lang.String displayNameKey, java.lang.String descriptionKey, Recurrence recur, java.lang.String[] resourceBundleIDs)
Constructs a new instance with the given recurrence and associate resource bundles

Method Summary

void	addExclusion(MetadataObjectId objectId) Adds a reference of an instance of ExclusionsDefinition in this Schedule object.
void	addExclusionDate(ExplicitDate date) Adds an explicit date to be excluded from occurrences in this Schedule object.
void	addInclusionDate(ExplicitDate date) Adds an explicit date to be included for occurrences in this Schedule object.
Schedule	clone(java.lang.String newName)
boolean	equals(java.lang.Object obj) Compares an object for equality with this Schedule object.
static Schedule	from(javax.management.openmbean.CompositeData cd) Create an instance of the model specific class out of an associated CompositeData instance
BaseMetadataType<Schedule>	getBaseMetadataType()
java.util.Collection<ExplicitDate>	getExclusionDates() Returns the list of dates excluded for occurrences in this Schedule object.
java.util.Collection<MetadataObjectId>	getExclusions() Returns the list of ExclusionsDefinition instance this object refers.
oracle.as.scheduler.runtime.ScheduleState	getFirstOccurrence(java.util.Calendar startTime, java.util.Calendar effectiveTime) Get the first occurrence of this schedule.
java.util.Collection<ExplicitDate>	getInclusionDates() Returns the list of explicit dates that are included for occurrences in this Schedule object.
java.util.Calendar	getNext(java.util.Calendar time) Returns the next occurrence as per the definition of this Schedule and the input timestamp.
java.util.Calendar	getNext(java.util.Calendar time, boolean firstTime, java.util.Calendar orig) Calculates and returns the next possible occurrence of this Schedule based on the given timestamp.
java.util.Calendar	getNext(java.util.Calendar time, java.util.Calendar orig) Computes the next occurrence based on the given time and the original start time.
oracle.as.scheduler.runtime.ScheduleState	getNext(oracle.as.scheduler.runtime.ScheduleState state)
Recurrence	getRecurrence() Returns the recurrence object of this schedule instance.
protected Schedule	getSelf()
java.util.TimeZone	getTimeZone() Returns the TimeZone set for this Schedule object.
java.util.Collection<java.util.Calendar>	list(java.util.Calendar begin, java.util.Calendar end) Generates a list of possible occurrences of this Schedule object within a given time period up to the default limit of 300.
java.util.Collection<java.util.Calendar>	list(java.util.Calendar begin, java.util.Calendar end, int limit) Generates a list of possible occurrences of this Schedule object within a given time period.
java.util.Collection<java.util.Calendar>	list(java.util.Calendar begin, int count) Generates a list of possible occurrences of this Schedule object starting with the given time upto the specified count.
void	removeExclusion(MetadataObjectId objectId) Removes the given reference of ExclusionsDefinition from this Schedule object.
void	removeExclusionDate(ExplicitDate date) Removes an explicit date from the list of dates excluded for occurrences in this Schedule object.
void	removeInclusionDate(ExplicitDate date) Removes an explicit date from list of included dates of this Schedule object.
void	setExclusionDates(java.util.Collection<ExplicitDate> dates) Sets the list of dates excluded for occurrences in this Schedule object.
void	setExclusionsDefinition(java.util.Collection<ExclusionsDefinition> exclusions) Sets the ExclusionsDefinition list to this Schedule.
void	setInclusionDates(java.util.Collection<ExplicitDate> dates) Sets the list of dates to be included for occurrences in this Schedule.
void	setRecurrence(Recurrence recur) Sets the recurrence for this schedule instance.
void	setTimeZone(java.util.TimeZone tz) Sets or clears the TimeZone for this Schedule object.
javax.management.openmbean.CompositeData	toCompositeData(javax.management.openmbean.CompositeType ct)
static javax.management.openmbean.CompositeType	toCompositeType() Returns the CompositeType that describes this model specific class
java.lang.String	toString() Returns a String representation for this Schedule object.
protected void	validateCustom() Validates this object.

Methods inherited from class oracle.as.scheduler.BaseMetadata

from, getDescription, getDescriptionKey, getDisplayName, getDisplayNameKey, getMessages, getMetadataObjectId, getName, getResourceBundles, hashCode, localize, setDescription, setDescriptionKey, setDisplayName, setDisplayNameKey, setResourceBundles, toCompositeData, validate

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_LIST_LIMIT

public static final int DEFAULT_LIST_LIMIT

See Also:

Constant Field Values

Constructor Detail

Schedule

public Schedule(java.lang.String name,
                java.lang.String description,
                Recurrence recur)

Constructs a new instance with the given recurrence.

Parameters:

name - name of the new instance. It cannot be null. The name is also used as the default display name unless otherwise specifially set.

description - an optional description.

recur - an instance of Recurrence object for this instance.

Schedule

public Schedule(java.lang.String name,
                java.lang.String displayNameKey,
                java.lang.String descriptionKey,
                Recurrence recur,
                java.lang.String[] resourceBundleIDs)

Constructs a new instance with the given recurrence and associate resource bundles

Parameters:

name - name of the new instance. It cannot be null. The name is also used as the default display name unless otherwise specifially set.

displayNameKey - - the key of the entry in the resourcebundles to lookup the name. Optional

descriptionKey - - the key of the entry in the resourcebundles to lookup the description. Optional.

recur - an instance of Recurrence object for this instance.

resourceBundleIDs - -- an array of resource bundle id. Optional.

Schedule

public Schedule(java.lang.String name,
                java.lang.String description,
                java.util.Collection<ExplicitDate> dates)

Constructs a new schedule with the given set of explicit dates.

Parameters:

name - the name for the new instance. It cannot be null. The name is also used as the default display name unless otherwise specifially set.

description - an optional description.

dates - a collection explicit dates for occurrences.

Schedule

public Schedule(java.lang.String name,
                java.lang.String displayNameKey,
                java.lang.String descriptionKey,
                java.util.Collection<ExplicitDate> dates,
                java.lang.String[] resourceBundleIDs)

Constructs a new schedule with the given set of explicit dates and associate resource bundles.

Parameters:

name - name of the new instance. It cannot be null. The name is also used as the default display name unless otherwise specifially set.

displayNameKey - - the key of the entry in the resourcebundles to lookup the name.

descriptionKey - - the key of the entry in the resourcebundles to lookup the description. Optional.

dates - a collection explicit dates for occurrences.

resourceBundleIDs - -- an array of resource bundle id

Schedule

public Schedule(java.lang.String name,
                java.lang.String description,
                Recurrence recur,
                MetadataObjectId objectId)

Constructs a new instance with the given recurrence.

This constructor is for internal use ONLY and should not be used to construct a new instance. This constructor is used internally by the MetadataService to populate the unique identifier of this object(definition) within the metadata repository.

Parameters:

name - name of the new instance. It cannot be null. The name is also used as the default display name unless otherwise specifially set.

description - an optional description.

recur - an instance of Recurrence object for this instance.

objectId - unique identifier of this object in the metadata repository. The identifier is set which this object is retrieved via MetadataService.

Schedule

public Schedule(java.lang.String name,
                java.lang.String description,
                java.util.Collection<ExplicitDate> dates,
                MetadataObjectId objectId)

Constructs a new schedule with the given set of explicit dates.

This constructor is for internal use ONLY and should not be used to construct a new instance. This constructor is used internally by the MetadataService to populate the unique identifier of this object(definition) within the metadata repository.

Parameters:

name - the name for the new instance. It cannot be null. The name is also used as the default display name unless otherwise specifially set.

description - an optional description.

dates - a collection explicit dates for occurrences.

objectId - unique identifier of this object in the metadata repository. The identifier is set which this object is retrieved via MetadataService.

Method Detail

getRecurrence

public Recurrence getRecurrence()

Returns the recurrence object of this schedule instance.

Returns:

recurrence of this object.

setRecurrence

public void setRecurrence(Recurrence recur)

Sets the recurrence for this schedule instance.

Parameters:

recur - name of this object.

addInclusionDate

public void addInclusionDate(ExplicitDate date)

Adds an explicit date to be included for occurrences in this Schedule object.

Parameters:

date - the explicit date to be included.

removeInclusionDate

public void removeInclusionDate(ExplicitDate date)

Removes an explicit date from list of included dates of this Schedule object.

Parameters:

date - the explicit date to be removed from the list of included dates.

setInclusionDates

public void setInclusionDates(java.util.Collection<ExplicitDate> dates)

Sets the list of dates to be included for occurrences in this Schedule.

Parameters:

dates - collection of explicit date to be included.

getInclusionDates

public java.util.Collection<ExplicitDate> getInclusionDates()

Returns the list of explicit dates that are included for occurrences in this Schedule object.

Returns:

collection of explicit dates that are included for occurrences in this object.

addExclusionDate

public void addExclusionDate(ExplicitDate date)

Adds an explicit date to be excluded from occurrences in this Schedule object.

Parameters:

date - the explicit date to be excluded.

removeExclusionDate

public void removeExclusionDate(ExplicitDate date)

Removes an explicit date from the list of dates excluded for occurrences in this Schedule object.

Parameters:

date - the explicit date to be removed from the list of excluded dates.

setExclusionDates

public void setExclusionDates(java.util.Collection<ExplicitDate> dates)

Sets the list of dates excluded for occurrences in this Schedule object.

Parameters:

dates - the list of explicit date to be excluded.

getExclusionDates

public java.util.Collection<ExplicitDate> getExclusionDates()

Returns the list of dates excluded for occurrences in this Schedule object.

Returns:

list of explicit date excluded for occurrences in this object.

addExclusion

public void addExclusion(MetadataObjectId objectId)

Adds a reference of an instance of ExclusionsDefinition in this Schedule object.

Parameters:

objectId - the identifier of the ExclusionsDefinition to be added.

removeExclusion

public void removeExclusion(MetadataObjectId objectId)

Removes the given reference of ExclusionsDefinition from this Schedule object.

Parameters:

objectId - identifier of the ExclusionsDefinition to be removed.

getExclusions

public java.util.Collection<MetadataObjectId> getExclusions()

Returns the list of ExclusionsDefinition instance this object refers.

Returns:

the list of identifiers for the ExclusionsDefinition object referred by this object.

setExclusionsDefinition

public void setExclusionsDefinition(java.util.Collection<ExclusionsDefinition> exclusions)

Sets the ExclusionsDefinition list to this Schedule. This is only used by the metadata service implementation and should not be used to set ExclusionsDefinition directly. The addExclusion method should be used instead.

Parameters:

exclusions - collection of ExclusionsDefinition objects to be set.

getTimeZone

public java.util.TimeZone getTimeZone()

Returns the TimeZone set for this Schedule object. If a Schedule object has as TimeZone set, it operates with respect to the set TimeZone. Otherwise the Schedule is TimeZone agnostic.

Returns:

TimeZone set in this Schedule object. Null otherwise.

setTimeZone

public void setTimeZone(java.util.TimeZone tz)

Sets or clears the TimeZone for this Schedule object. A null TimeZone make the Schedule time zone agnostic.

Parameters:

tz - the TimeZone to be set for this object. NULL if the TimeZone needs to be cleared/unset.

getFirstOccurrence

public oracle.as.scheduler.runtime.ScheduleState getFirstOccurrence(java.util.Calendar startTime,
                                                                    java.util.Calendar effectiveTime)

Get the first occurrence of this schedule. The value must be after both startTime and effectiveTime. startTime may, in some cases, be used as a template for missing time fields.

Parameters:

startTime - Represents the time on which the first occurrence is generated. This value can be used both as a lower boundary on the schedule and a template for missing fields in a recurrence.

effectiveTime - Represents a lower boundary on the schedule. No occurrences will be generated before this time.

getNext

public java.util.Calendar getNext(java.util.Calendar time)

Returns the next occurrence as per the definition of this Schedule and the input timestamp.

Parameters:

time - timestamp based on which the occurrence will be calculated.

Returns:

occurrence based on the input timestamp if possible, otherwise the method returns null.

getNext

public java.util.Calendar getNext(java.util.Calendar time,
                                  java.util.Calendar orig)

Computes the next occurrence based on the given time and the original start time. This original start time reflects the requested start time for a request for which the next time is being calculated.

Parameters:

time - timestamp representing previous occurrence. This can be the one from the recurrence pattern or an explicit date that this Schedule object returned last time.

orig - original requested start time for the request for which the next time is being calculated. The Schedule may or may not use it.

Returns:

next occurrence based on the input parameters. This can be one from the recurrence pattern or next explicit date (if present) whichever is earlier. If no occurrence is possible, the method returns null.

getNext

public java.util.Calendar getNext(java.util.Calendar time,
                                  boolean firstTime,
                                  java.util.Calendar orig)

Calculates and returns the next possible occurrence of this Schedule based on the given timestamp.

To compute the next possible occurrence, the method takes into account the recurrence, the list of inclusions dates, list of exclusion dates as well and shared ExclusionsDefinition this object refers to.

Based on the end date/time or the count if specified for this object, the Schedule will stop generating occurrences and return 0. This must be interpreted as end of this Schedule.

Parameters:

time - the time on which the next occurrence will be generated.

firstTime - flag indicating whether the call is for first occurrence or not.

orig - original timestamp with which the occurrences started.

Returns:

the next occurrence as long or null if no occurrence is possible.

getNext

public oracle.as.scheduler.runtime.ScheduleState getNext(oracle.as.scheduler.runtime.ScheduleState state)

list

public java.util.Collection<java.util.Calendar> list(java.util.Calendar begin,
                                                     java.util.Calendar end)
                                              throws IllegalArgumentException

Generates a list of possible occurrences of this Schedule object within a given time period up to the default limit of 300.

Parameters:

begin - the start date/time for listing possible occurrences, inclusive, not null.

end - the end date/time for listing possible occurrences, inclusive, not null.

Returns:

a collection of Calendar instances representing possible occurrences. null if no occurrences are possible in the given time period. The maximum number of results are limitted by the property DEFAULT_LIST_LIMIT of 300 occurences.

Throws:

IllegalArgumentException

list

public java.util.Collection<java.util.Calendar> list(java.util.Calendar begin,
                                                     int count)
                                              throws IllegalArgumentException

Generates a list of possible occurrences of this Schedule object starting with the given time upto the specified count.

Parameters:

begin - the start date/time for listing occurrences, inclusive, not null.

count - the maximum number of occurrences to be listed.

Returns:

a collection of Calendar instances representing possible occurrences up to the specified count, or null if no occurrences are possible.

Throws:

IllegalArgumentException

list

public java.util.Collection<java.util.Calendar> list(java.util.Calendar begin,
                                                     java.util.Calendar end,
                                                     int limit)
                                              throws IllegalArgumentException

Generates a list of possible occurrences of this Schedule object within a given time period.

Parameters:

begin - the start date/time for listing possible occurrences, inclusive, not null.

end - the end date/time for listing possible occurrences, inclusive.

limit - the maximum number of occurrences to be listed. The limit has to be a positive integer or zero. A zero limit results an empty list.

Returns:

a collection of Calendar instances representing possible occurrences up to the specified limit. null if no occurrences are possible in the given time period.

Throws:

IllegalArgumentException

validateCustom

protected void validateCustom()
                       throws ValidationException

Validates this object. The method checks all the fields contained in the object and verifies that the object is a valid Schedule instance. The method does not check any referenced objects. Such references and related validations are done by the MetadataService at the time of persistence.

Specified by:

validateCustom in class BaseMetadata<Schedule>

Throws:

ValidationException - thrown if any validation errors are found.

equals

public boolean equals(java.lang.Object obj)

Compares an object for equality with this Schedule object.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to compare with this Schedule.

Returns:

true if the object passed in is an instance of Schedule and is equal to this Schedule, false otherwise.

toString

public java.lang.String toString()

Returns a String representation for this Schedule object.

Overrides:

toString in class BaseMetadata<Schedule>

Returns:

String representing this Schedule.

toCompositeType

public static javax.management.openmbean.CompositeType toCompositeType()

Returns the CompositeType that describes this model specific class

toCompositeData

public javax.management.openmbean.CompositeData toCompositeData(javax.management.openmbean.CompositeType ct)

Specified by:

toCompositeData in class BaseMetadata<Schedule>

from

public static Schedule from(javax.management.openmbean.CompositeData cd)
                     throws java.lang.IllegalArgumentException

Create an instance of the model specific class out of an associated CompositeData instance

Throws:

java.lang.IllegalArgumentException

getSelf

protected Schedule getSelf()

Specified by:

getSelf in class BaseMetadata<Schedule>

getBaseMetadataType

public BaseMetadataType<Schedule> getBaseMetadataType()

Specified by:

getBaseMetadataType in class BaseMetadata<Schedule>

clone

public Schedule clone(java.lang.String newName)

Specified by:

clone in class BaseMetadata<Schedule>