org.quartz.CalendarIntervalTrigger Maven / Gradle / Ivy
/*
* All content copyright Terracotta, Inc., unless otherwise indicated. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy
* of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*
*/
package org.quartz;
import java.util.Calendar;
import java.util.TimeZone;
import org.quartz.DateBuilder.IntervalUnit;
/**
* A concrete {@link Trigger} that is used to fire a {@link org.quartz.JobDetail}
* based upon repeating calendar time intervals.
*
* The trigger will fire every N (see {@link #setRepeatInterval(int)} ) units of calendar time
* (see {@link #setRepeatIntervalUnit(IntervalUnit)}) as specified in the trigger's definition.
* This trigger can achieve schedules that are not possible with {@link SimpleTrigger} (e.g
* because months are not a fixed number of seconds) or {@link CronTrigger} (e.g. because
* "every 5 months" is not an even divisor of 12).
*
* If you use an interval unit of MONTH then care should be taken when setting
* a startTime value that is on a day near the end of the month. For example,
* if you choose a start time that occurs on January 31st, and have a trigger with unit
* MONTH and interval 1, then the next fire time will be February 28th,
* and the next time after that will be March 28th - and essentially each subsequent firing will
* occur on the 28th of the month, even if a 31st day exists. If you want a trigger that always
* fires on the last day of the month - regardless of the number of days in the month,
* you should use CronTrigger.
*
* @see TriggerBuilder
* @see CalendarIntervalScheduleBuilder
* @see SimpleScheduleBuilder
* @see CronScheduleBuilder
*
* @author James House
*/
public interface CalendarIntervalTrigger extends Trigger {
/**
*
* Instructs the {@link Scheduler} that upon a mis-fire
* situation, the {@link CalendarIntervalTrigger} wants to be
* fired now by Scheduler.
*
*/
public static final int MISFIRE_INSTRUCTION_FIRE_ONCE_NOW = 1;
/**
*
* Instructs the {@link Scheduler} that upon a mis-fire
* situation, the {@link CalendarIntervalTrigger} wants to have it's
* next-fire-time updated to the next time in the schedule after the
* current time (taking into account any associated {@link Calendar},
* but it does not want to be fired now.
*
*/
public static final int MISFIRE_INSTRUCTION_DO_NOTHING = 2;
/**
* Get the interval unit - the time unit on with the interval applies.
*/
public IntervalUnit getRepeatIntervalUnit();
/**
*
* Get the the time interval that will be added to the DateIntervalTrigger's
* fire time (in the set repeat interval unit) in order to calculate the time of the
* next trigger repeat.
*
*/
public int getRepeatInterval();
/**
*
* Get the number of times the DateIntervalTrigger has already
* fired.
*
*/
public int getTimesTriggered();
/**
*
* Gets the time zone within which time calculations related to this
* trigger will be performed.
*
*
*
* If null, the system default TimeZone will be used.
*
*/
public TimeZone getTimeZone();
/**
* If intervals are a day or greater, this property (set to true) will
* cause the firing of the trigger to always occur at the same time of day,
* (the time of day of the startTime) regardless of daylight saving time
* transitions. Default value is false.
*
*
* For example, without the property set, your trigger may have a start
* time of 9:00 am on March 1st, and a repeat interval of 2 days. But
* after the daylight saving transition occurs, the trigger may start
* firing at 8:00 am every other day.
*
*
*
* If however, the time of day does not exist on a given day to fire
* (e.g. 2:00 am in the United States on the days of daylight saving
* transition), the trigger will go ahead and fire one hour off on
* that day, and then resume the normal hour on other days. If
* you wish for the trigger to never fire at the "wrong" hour, then
* you should set the property skipDayIfHourDoesNotExist.
*
*
* @see #isSkipDayIfHourDoesNotExist()
* @see #getStartTime()
* @see #getTimeZone()
*/
public boolean isPreserveHourOfDayAcrossDaylightSavings();
/**
* If intervals are a day or greater, and
* preserveHourOfDayAcrossDaylightSavings property is set to true, and the
* hour of the day does not exist on a given day for which the trigger
* would fire, the day will be skipped and the trigger advanced a second
* interval if this property is set to true. Defaults to false.
*
*
* CAUTION! If you enable this property, and your hour of day happens
* to be that of daylight savings transition (e.g. 2:00 am in the United
* States) and the trigger's interval would have had the trigger fire on
* that day, then you may actually completely miss a firing on the day of
* transition if that hour of day does not exist on that day! In such a
* case the next fire time of the trigger will be computed as double (if
* the interval is 2 days, then a span of 4 days between firings will
* occur).
*
*
* @see #isPreserveHourOfDayAcrossDaylightSavings()
*/
public boolean isSkipDayIfHourDoesNotExist();
TriggerBuilder getTriggerBuilder();
}