org.quartz
Class Trigger

java.lang.Object
  extended by org.quartz.Trigger
All Implemented Interfaces:
Serializable, Cloneable, Comparable
Direct Known Subclasses:
CronTrigger, DateIntervalTrigger, NthIncludedDayTrigger, SimpleTrigger

public abstract class Trigger
extends Object
implements Serializable, Cloneable, Comparable

The base abstract class to be extended by all Triggers.

Triggers s have a name and group associated with them, which should uniquely identify them within a single Scheduler.

Triggers are the 'mechanism' by which Job s are scheduled. Many Trigger s can point to the same Job, but a single Trigger can only point to one Job.

Triggers can 'send' parameters/data to Jobs by placing contents into the JobDataMap on the Trigger.

Author:
James House, Sharada Jambula
See Also:
SimpleTrigger, CronTrigger, NthIncludedDayTrigger, TriggerUtils, JobDataMap, JobExecutionContext, Serialized Form

Field Summary
static int DEFAULT_PRIORITY
          The default value for priority.
static int INSTRUCTION_DELETE_TRIGGER
           Instructs the Scheduler that the Trigger wants itself deleted.
static int INSTRUCTION_NOOP
           Instructs the Scheduler that the Trigger has no further instructions.
static int INSTRUCTION_RE_EXECUTE_JOB
           Instructs the Scheduler that the Trigger wants the JobDetail to re-execute immediately.
static int INSTRUCTION_SET_ALL_JOB_TRIGGERS_COMPLETE
           Instructs the Scheduler that all Trigger s referencing the same JobDetail as this one should be put in the COMPLETE state.
static int INSTRUCTION_SET_ALL_JOB_TRIGGERS_ERROR
           Instructs the Scheduler that the Trigger should be put in the ERROR state.
static int INSTRUCTION_SET_TRIGGER_COMPLETE
           Instructs the Scheduler that the Trigger should be put in the COMPLETE state.
static int INSTRUCTION_SET_TRIGGER_ERROR
           Instructs the Scheduler that all Trigger s referencing the same JobDetail as this one should be put in the ERROR state.
static int MISFIRE_INSTRUCTION_SMART_POLICY
           Instructs the Scheduler that upon a mis-fire situation, the updateAfterMisfire() method will be called on the Trigger to determine the mis-fire instruction.
static int STATE_BLOCKED
           Indicates that the Trigger is in the "blocked" state.
static int STATE_COMPLETE
           Indicates that the Trigger is in the "complete" state.
static int STATE_ERROR
           Indicates that the Trigger is in the "error" state.
static int STATE_NONE
           Indicates that the Trigger does not exist.
static int STATE_NORMAL
           Indicates that the Trigger is in the "normal" state.
static int STATE_PAUSED
           Indicates that the Trigger is in the "paused" state.
 
Constructor Summary
Trigger()
           Create a Trigger with no specified name, group, or JobDetail.
Trigger(String name)
           Create a Trigger with the given name, and default group.
Trigger(String name, String group)
           Create a Trigger with the given name, and group.
Trigger(String name, String group, String jobName, String jobGroup)
           Create a Trigger with the given name, and group.
 
Method Summary
 void addTriggerListener(String name)
           Add the specified name of a TriggerListener to the end of the Trigger's list of listeners.
 void clearAllTriggerListeners()
          Remove all TriggerListeners from the Trigger.
 Object clone()
           
 int compareTo(Object obj)
           Compare the next fire time of this Trigger to that of another.
abstract  Date computeFirstFireTime(Calendar calendar)
           This method should not be used by the Quartz client.
 boolean equals(Object obj)
           
abstract  int executionComplete(JobExecutionContext context, JobExecutionException result)
           This method should not be used by the Quartz client.
 String getCalendarName()
           Get the name of the Calendar associated with this Trigger.
 String getDescription()
           Return the description given to the Trigger instance by its creator (if any).
abstract  Date getEndTime()
           Get the time at which the Trigger should quit repeating - regardless of any remaining repeats (based on the trigger's particular repeat settings).
abstract  Date getFinalFireTime()
           Returns the last time at which the Trigger will fire, if the Trigger will repeat indefinitely, null will be returned.
 String getFireInstanceId()
           This method should not be used by the Quartz client.
abstract  Date getFireTimeAfter(Date afterTime)
           Returns the next time at which the Trigger will fire, after the given time.
 String getFullJobName()
           Returns the 'full name' of the Job that the Trigger points to, in the format "group.name".
 String getFullName()
           Returns the 'full name' of the Trigger in the format "group.name".
 String getGroup()
           Get the group of this Trigger.
 JobDataMap getJobDataMap()
           Get the JobDataMap that is associated with the Trigger.
 String getJobGroup()
           Get the name of the associated JobDetail's group.
 String getJobName()
           Get the name of the associated JobDetail.
 Key getKey()
           
 int getMisfireInstruction()
           Get the instruction the Scheduler should be given for handling misfire situations for this Trigger- the concrete Trigger type that you are using will have defined a set of additional MISFIRE_INSTRUCTION_XXX constants that may be passed to this method.
 String getName()
           Get the name of this Trigger.
abstract  Date getNextFireTime()
           Returns the next time at which the Trigger is scheduled to fire.
abstract  Date getPreviousFireTime()
           Returns the previous time at which the Trigger fired.
 int getPriority()
          The priority of a Trigger acts as a tiebreaker such that if two Triggers have the same scheduled fire time, then the one with the higher priority will get first access to a worker thread.
abstract  Date getStartTime()
           Get the time at which the Trigger should occur.
 String[] getTriggerListenerNames()
           Returns an array of String containing the names of all TriggerListeners assigned to the Trigger, in the order in which they should be notified.
 int hashCode()
           
 boolean isVolatile()
           Whether or not the Trigger should be persisted in the JobStore for re-use after program restarts.
abstract  boolean mayFireAgain()
           Used by the Scheduler to determine whether or not it is possible for this Trigger to fire again.
 boolean removeTriggerListener(String name)
           Remove the specified name of a TriggerListener from the Trigger's list of listeners.
 void setCalendarName(String calendarName)
           Associate the Calendar with the given name with this Trigger.
 void setDescription(String description)
           Set a description for the Trigger instance - may be useful for remembering/displaying the purpose of the trigger, though the description has no meaning to Quartz.
abstract  void setEndTime(Date endTime)
           Set the time at which the Trigger should quit repeating - regardless of any remaining repeats (based on the trigger's particular repeat settings).
 void setFireInstanceId(String id)
           This method should not be used by the Quartz client.
 void setGroup(String group)
           Set the name of this Trigger.
 void setJobDataMap(JobDataMap jobDataMap)
           Set the JobDataMap to be associated with the Trigger.
 void setJobGroup(String jobGroup)
           Set the name of the associated JobDetail's group.
 void setJobName(String jobName)
           Set the name of the associated JobDetail.
 void setMisfireInstruction(int misfireInstruction)
           Set the instruction the Scheduler should be given for handling misfire situations for this Trigger- the concrete Trigger type that you are using will have defined a set of additional MISFIRE_INSTRUCTION_XXX constants that may be passed to this method.
 void setName(String name)
           Set the name of this Trigger.
 void setPriority(int priority)
          The priority of a Trigger acts as a tie breaker such that if two Triggers have the same scheduled fire time, then Quartz will do its best to give the one with the higher priority first access to a worker thread.
abstract  void setStartTime(Date startTime)
           The time at which the trigger's scheduling should start.
 void setVolatility(boolean volatility)
           Set whether or not the Trigger should be persisted in the JobStore for re-use after program restarts.
 String toString()
           Return a simple string representation of this object.
abstract  void triggered(Calendar calendar)
           This method should not be used by the Quartz client.
abstract  void updateAfterMisfire(Calendar cal)
           This method should not be used by the Quartz client.
abstract  void updateWithNewCalendar(Calendar cal, long misfireThreshold)
           This method should not be used by the Quartz client.
 void validate()
           Validates whether the properties of the JobDetail are valid for submission into a Scheduler.
protected abstract  boolean validateMisfireInstruction(int misfireInstruction)
           
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

INSTRUCTION_NOOP

public static final int INSTRUCTION_NOOP

Instructs the Scheduler that the Trigger has no further instructions.

See Also:
Constant Field Values

INSTRUCTION_RE_EXECUTE_JOB

public static final int INSTRUCTION_RE_EXECUTE_JOB

Instructs the Scheduler that the Trigger wants the JobDetail to re-execute immediately. If not in a 'RECOVERING' or 'FAILED_OVER' situation, the execution context will be re-used (giving the Job the ability to 'see' anything placed in the context by its last execution).

See Also:
Constant Field Values

INSTRUCTION_SET_TRIGGER_COMPLETE

public static final int INSTRUCTION_SET_TRIGGER_COMPLETE

Instructs the Scheduler that the Trigger should be put in the COMPLETE state.

See Also:
Constant Field Values

INSTRUCTION_DELETE_TRIGGER

public static final int INSTRUCTION_DELETE_TRIGGER

Instructs the Scheduler that the Trigger wants itself deleted.

See Also:
Constant Field Values

INSTRUCTION_SET_ALL_JOB_TRIGGERS_COMPLETE

public static final int INSTRUCTION_SET_ALL_JOB_TRIGGERS_COMPLETE

Instructs the Scheduler that all Trigger s referencing the same JobDetail as this one should be put in the COMPLETE state.

See Also:
Constant Field Values

INSTRUCTION_SET_TRIGGER_ERROR

public static final int INSTRUCTION_SET_TRIGGER_ERROR

Instructs the Scheduler that all Trigger s referencing the same JobDetail as this one should be put in the ERROR state.

See Also:
Constant Field Values

INSTRUCTION_SET_ALL_JOB_TRIGGERS_ERROR

public static final int INSTRUCTION_SET_ALL_JOB_TRIGGERS_ERROR

Instructs the Scheduler that the Trigger should be put in the ERROR state.

See Also:
Constant Field Values

MISFIRE_INSTRUCTION_SMART_POLICY

public static final int MISFIRE_INSTRUCTION_SMART_POLICY

Instructs the Scheduler that upon a mis-fire situation, the updateAfterMisfire() method will be called on the Trigger to determine the mis-fire instruction.

In order to see if this instruction fits your needs, you should look at the documentation for the getSmartMisfirePolicy() method on the particular Trigger implementation you are using.

See Also:
Constant Field Values

STATE_NORMAL

public static final int STATE_NORMAL

Indicates that the Trigger is in the "normal" state.

See Also:
Constant Field Values

STATE_PAUSED

public static final int STATE_PAUSED

Indicates that the Trigger is in the "paused" state.

See Also:
Constant Field Values

STATE_COMPLETE

public static final int STATE_COMPLETE

Indicates that the Trigger is in the "complete" state.

"Complete" indicates that the trigger has not remaining fire-times in its schedule.

See Also:
Constant Field Values

STATE_ERROR

public static final int STATE_ERROR

Indicates that the Trigger is in the "error" state.

A Trigger arrives at the error state when the scheduler attempts to fire it, but cannot due to an error creating and executing its related job. Often this is due to the Job's class not existing in the classpath.

When the trigger is in the error state, the scheduler will make no attempts to fire it.

See Also:
Constant Field Values

STATE_BLOCKED

public static final int STATE_BLOCKED

Indicates that the Trigger is in the "blocked" state.

A Trigger arrives at the blocked state when the job that it is associated with is a StatefulJob and it is currently executing.

See Also:
StatefulJob, Constant Field Values

STATE_NONE

public static final int STATE_NONE

Indicates that the Trigger does not exist.

See Also:
Constant Field Values

DEFAULT_PRIORITY

public static final int DEFAULT_PRIORITY
The default value for priority.

See Also:
Constant Field Values
Constructor Detail

Trigger

public Trigger()

Create a Trigger with no specified name, group, or JobDetail.

Note that the setName(String),setGroup(String)and the setJobName(String)and setJobGroup(String)methods must be called before the Trigger can be placed into a Scheduler.


Trigger

public Trigger(String name)

Create a Trigger with the given name, and default group.

Note that the setJobName(String)and setJobGroup(String)methods must be called before the Trigger can be placed into a Scheduler.

Parameters:
group - if null, Scheduler.DEFAULT_GROUP will be used.
Throws:
IllegalArgumentException - if name is null or empty, or the group is an empty string.

Trigger

public Trigger(String name,
               String group)

Create a Trigger with the given name, and group.

Note that the setJobName(String)and setJobGroup(String)methods must be called before the Trigger can be placed into a Scheduler.

Parameters:
group - if null, Scheduler.DEFAULT_GROUP will be used.
Throws:
IllegalArgumentException - if name is null or empty, or the group is an empty string.

Trigger

public Trigger(String name,
               String group,
               String jobName,
               String jobGroup)

Create a Trigger with the given name, and group.

Parameters:
group - if null, Scheduler.DEFAULT_GROUP will be used.
Throws:
IllegalArgumentException - if name is null or empty, or the group is an empty string.
Method Detail

getName

public String getName()

Get the name of this Trigger.


setName

public void setName(String name)

Set the name of this Trigger.

Throws:
IllegalArgumentException - if name is null or empty.

getGroup

public String getGroup()

Get the group of this Trigger.


setGroup

public void setGroup(String group)

Set the name of this Trigger.

Parameters:
group - if null, Scheduler.DEFAULT_GROUP will be used.
Throws:
IllegalArgumentException - if group is an empty string.

getJobName

public String getJobName()

Get the name of the associated JobDetail.


setJobName

public void setJobName(String jobName)

Set the name of the associated JobDetail.

Throws:
IllegalArgumentException - if jobName is null or empty.

getJobGroup

public String getJobGroup()

Get the name of the associated JobDetail's group.


setJobGroup

public void setJobGroup(String jobGroup)

Set the name of the associated JobDetail's group.

Parameters:
jobGroup - if null, Scheduler.DEFAULT_GROUP will be used.
Throws:
IllegalArgumentException - if group is an empty string.

getFullName

public String getFullName()

Returns the 'full name' of the Trigger in the format "group.name".


getKey

public Key getKey()

getFullJobName

public String getFullJobName()

Returns the 'full name' of the Job that the Trigger points to, in the format "group.name".


getDescription

public String getDescription()

Return the description given to the Trigger instance by its creator (if any).

Returns:
null if no description was set.

setDescription

public void setDescription(String description)

Set a description for the Trigger instance - may be useful for remembering/displaying the purpose of the trigger, though the description has no meaning to Quartz.


setVolatility

public void setVolatility(boolean volatility)

Set whether or not the Trigger should be persisted in the JobStore for re-use after program restarts.


setCalendarName

public void setCalendarName(String calendarName)

Associate the Calendar with the given name with this Trigger.

Parameters:
calendarName - use null to dis-associate a Calendar.

getCalendarName

public String getCalendarName()

Get the name of the Calendar associated with this Trigger.

Returns:
null if there is no associated Calendar.

getJobDataMap

public JobDataMap getJobDataMap()

Get the JobDataMap that is associated with the Trigger.

Changes made to this map during job execution are not re-persisted, and in fact typically result in an IllegalStateException.


setJobDataMap

public void setJobDataMap(JobDataMap jobDataMap)

Set the JobDataMap to be associated with the Trigger.


isVolatile

public boolean isVolatile()

Whether or not the Trigger should be persisted in the JobStore for re-use after program restarts.

If not explicitly set, the default value is false.

Returns:
true if the Trigger should be garbage collected along with the Scheduler.

getPriority

public int getPriority()
The priority of a Trigger acts as a tiebreaker such that if two Triggers have the same scheduled fire time, then the one with the higher priority will get first access to a worker thread.

If not explicitly set, the default value is 5.

See Also:
DEFAULT_PRIORITY

setPriority

public void setPriority(int priority)
The priority of a Trigger acts as a tie breaker such that if two Triggers have the same scheduled fire time, then Quartz will do its best to give the one with the higher priority first access to a worker thread.

If not explicitly set, the default value is 5.

See Also:
DEFAULT_PRIORITY

addTriggerListener

public void addTriggerListener(String name)

Add the specified name of a TriggerListener to the end of the Trigger's list of listeners.


removeTriggerListener

public boolean removeTriggerListener(String name)

Remove the specified name of a TriggerListener from the Trigger's list of listeners.

Returns:
true if the given name was found in the list, and removed

getTriggerListenerNames

public String[] getTriggerListenerNames()

Returns an array of String containing the names of all TriggerListeners assigned to the Trigger, in the order in which they should be notified.


clearAllTriggerListeners

public void clearAllTriggerListeners()
Remove all TriggerListeners from the Trigger.


triggered

public abstract void triggered(Calendar calendar)

This method should not be used by the Quartz client.

Called when the Scheduler has decided to 'fire' the trigger (execute the associated Job), in order to give the Trigger a chance to update itself for its next triggering (if any).

See Also:
executionComplete(JobExecutionContext, JobExecutionException)

computeFirstFireTime

public abstract Date computeFirstFireTime(Calendar calendar)

This method should not be used by the Quartz client.

Called by the scheduler at the time a Trigger is first added to the scheduler, in order to have the Trigger compute its first fire time, based on any associated calendar.

After this method has been called, getNextFireTime() should return a valid answer.

Returns:
the first time at which the Trigger will be fired by the scheduler, which is also the same value getNextFireTime() will return (until after the first firing of the Trigger).


executionComplete

public abstract int executionComplete(JobExecutionContext context,
                                      JobExecutionException result)

This method should not be used by the Quartz client.

Called after the Scheduler has executed the JobDetail associated with the Trigger in order to get the final instruction code from the trigger.

Parameters:
context - is the JobExecutionContext that was used by the Job'sexecute(xx) method.
result - is the JobExecutionException thrown by the Job, if any (may be null).
Returns:
one of the Trigger.INSTRUCTION_XXX constants.
See Also:
INSTRUCTION_NOOP, INSTRUCTION_RE_EXECUTE_JOB, INSTRUCTION_DELETE_TRIGGER, INSTRUCTION_SET_TRIGGER_COMPLETE, triggered(Calendar)

mayFireAgain

public abstract boolean mayFireAgain()

Used by the Scheduler to determine whether or not it is possible for this Trigger to fire again.

If the returned value is false then the Scheduler may remove the Trigger from the JobStore.


getStartTime

public abstract Date getStartTime()

Get the time at which the Trigger should occur.


setStartTime

public abstract void setStartTime(Date startTime)

The time at which the trigger's scheduling should start. May or may not be the first actual fire time of the trigger, depending upon the type of trigger and the settings of the other properties of the trigger. However the first actual first time will not be before this date.

Setting a value in the past may cause a new trigger to compute a first fire time that is in the past, which may cause an immediate misfire of the trigger.


setEndTime

public abstract void setEndTime(Date endTime)

Set the time at which the Trigger should quit repeating - regardless of any remaining repeats (based on the trigger's particular repeat settings).

See Also:
TriggerUtils.computeEndTimeToAllowParticularNumberOfFirings(Trigger, Calendar, int)

getEndTime

public abstract Date getEndTime()

Get the time at which the Trigger should quit repeating - regardless of any remaining repeats (based on the trigger's particular repeat settings).

See Also:
getFinalFireTime()

getNextFireTime

public abstract Date getNextFireTime()

Returns the next time at which the Trigger is scheduled to fire. If the trigger will not fire again, null will be returned. Note that the time returned can possibly be in the past, if the time that was computed for the trigger to next fire has already arrived, but the scheduler has not yet been able to fire the trigger (which would likely be due to lack of resources e.g. threads).

The value returned is not guaranteed to be valid until after the Trigger has been added to the scheduler.

See Also:
TriggerUtils.computeFireTimesBetween(Trigger, Calendar, Date, Date)

getPreviousFireTime

public abstract Date getPreviousFireTime()

Returns the previous time at which the Trigger fired. If the trigger has not yet fired, null will be returned.


getFireTimeAfter

public abstract Date getFireTimeAfter(Date afterTime)

Returns the next time at which the Trigger will fire, after the given time. If the trigger will not fire after the given time, null will be returned.


getFinalFireTime

public abstract Date getFinalFireTime()

Returns the last time at which the Trigger will fire, if the Trigger will repeat indefinitely, null will be returned.

Note that the return time *may* be in the past.


setMisfireInstruction

public void setMisfireInstruction(int misfireInstruction)

Set the instruction the Scheduler should be given for handling misfire situations for this Trigger- the concrete Trigger type that you are using will have defined a set of additional MISFIRE_INSTRUCTION_XXX constants that may be passed to this method.

If not explicitly set, the default value is MISFIRE_INSTRUCTION_SMART_POLICY.

See Also:
MISFIRE_INSTRUCTION_SMART_POLICY, updateAfterMisfire(Calendar), SimpleTrigger, CronTrigger

validateMisfireInstruction

protected abstract boolean validateMisfireInstruction(int misfireInstruction)

getMisfireInstruction

public int getMisfireInstruction()

Get the instruction the Scheduler should be given for handling misfire situations for this Trigger- the concrete Trigger type that you are using will have defined a set of additional MISFIRE_INSTRUCTION_XXX constants that may be passed to this method.

If not explicitly set, the default value is MISFIRE_INSTRUCTION_SMART_POLICY.

See Also:
MISFIRE_INSTRUCTION_SMART_POLICY, updateAfterMisfire(Calendar), SimpleTrigger, CronTrigger

updateAfterMisfire

public abstract void updateAfterMisfire(Calendar cal)

This method should not be used by the Quartz client.

To be implemented by the concrete classes that extend this class.

The implementation should update the Trigger's state based on the MISFIRE_INSTRUCTION_XXX that was selected when the Trigger was created.


updateWithNewCalendar

public abstract void updateWithNewCalendar(Calendar cal,
                                           long misfireThreshold)

This method should not be used by the Quartz client.

To be implemented by the concrete class.

The implementation should update the Trigger's state based on the given new version of the associated Calendar (the state should be updated so that it's next fire time is appropriate given the Calendar's new settings).

Parameters:
cal -

validate

public void validate()
              throws SchedulerException

Validates whether the properties of the JobDetail are valid for submission into a Scheduler.

Throws:
IllegalStateException - if a required property (such as Name, Group, Class) is not set.
SchedulerException

setFireInstanceId

public void setFireInstanceId(String id)

This method should not be used by the Quartz client.

Usable by JobStore implementations, in order to facilitate 'recognizing' instances of fired Trigger s as their jobs complete execution.


getFireInstanceId

public String getFireInstanceId()

This method should not be used by the Quartz client.


toString

public String toString()

Return a simple string representation of this object.

Overrides:
toString in class Object

compareTo

public int compareTo(Object obj)

Compare the next fire time of this Trigger to that of another.

Specified by:
compareTo in interface Comparable

equals

public boolean equals(Object obj)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

clone

public Object clone()
Overrides:
clone in class Object


Copyright 2001-2011, Terracotta, Inc.