org.quartz
Class Trigger

java.lang.Object
  org.quartz.Trigger

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

Direct Known Subclasses:

CronTrigger, DateIntervalTrigger, NthIncludedDayTrigger, SimpleTrigger

public abstract class Trigger
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable, java.lang.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(java.lang.String name)
Create a Trigger with the given name, and default group.

Trigger(java.lang.String name, java.lang.String group)
Create a Trigger with the given name, and group.

Trigger(java.lang.String name, java.lang.String group, java.lang.String jobName, java.lang.String jobGroup)
Create a Trigger with the given name, and group.

Method Summary

void	addTriggerListener(java.lang.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.
java.lang.Object	clone()
int	compareTo(java.lang.Object obj) Compare the next fire time of this Trigger to that of another.
abstract java.util.Date	computeFirstFireTime(Calendar calendar) This method should not be used by the Quartz client.
boolean	equals(java.lang.Object obj)
abstract int	executionComplete(JobExecutionContext context, JobExecutionException result) This method should not be used by the Quartz client.
java.lang.String	getCalendarName() Get the name of the Calendar associated with this Trigger.
java.lang.String	getDescription() Return the description given to the Trigger instance by its creator (if any).
abstract java.util.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 java.util.Date	getFinalFireTime() Returns the last time at which the Trigger will fire, if the Trigger will repeat indefinitely, null will be returned.
java.lang.String	getFireInstanceId() This method should not be used by the Quartz client.
abstract java.util.Date	getFireTimeAfter(java.util.Date afterTime) Returns the next time at which the Trigger will fire, after the given time.
java.lang.String	getFullJobName() Returns the 'full name' of the Job that the Trigger points to, in the format "group.name".
java.lang.String	getFullName() Returns the 'full name' of the Trigger in the format "group.name".
java.lang.String	getGroup() Get the group of this Trigger.
JobDataMap	getJobDataMap() Get the JobDataMap that is associated with the Trigger.
java.lang.String	getJobGroup() Get the name of the associated JobDetail's group.
java.lang.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.
java.lang.String	getName() Get the name of this Trigger.
abstract java.util.Date	getNextFireTime() Returns the next time at which the Trigger is scheduled to fire.
abstract java.util.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 java.util.Date	getStartTime() Get the time at which the Trigger should occur.
java.lang.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(java.lang.String name) Remove the specified name of a TriggerListener from the Trigger's list of listeners.
void	setCalendarName(java.lang.String calendarName) Associate the Calendar with the given name with this Trigger.
void	setDescription(java.lang.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(java.util.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(java.lang.String id) This method should not be used by the Quartz client.
void	setGroup(java.lang.String group) Set the name of this Trigger.
void	setJobDataMap(JobDataMap jobDataMap) Set the JobDataMap to be associated with the Trigger.
void	setJobGroup(java.lang.String jobGroup) Set the name of the associated JobDetail's group.
void	setJobName(java.lang.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(java.lang.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(java.util.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.
java.lang.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(java.lang.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:

java.lang.IllegalArgumentException - if name is null or empty, or the group is an empty string.

Trigger

public Trigger(java.lang.String name,
               java.lang.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:

java.lang.IllegalArgumentException - if name is null or empty, or the group is an empty string.

Trigger

public Trigger(java.lang.String name,
               java.lang.String group,
               java.lang.String jobName,
               java.lang.String jobGroup)

Create a Trigger with the given name, and group.

Parameters:

group - if null, Scheduler.DEFAULT_GROUP will be used.

Throws:

java.lang.IllegalArgumentException - if name is null or empty, or the group is an empty string.

Method Detail

getName

public java.lang.String getName()

Get the name of this Trigger.

setName

public void setName(java.lang.String name)

Set the name of this Trigger.

Throws:

java.lang.IllegalArgumentException - if name is null or empty.

getGroup

public java.lang.String getGroup()

Get the group of this Trigger.

setGroup

public void setGroup(java.lang.String group)

Set the name of this Trigger.

Parameters:

group - if null, Scheduler.DEFAULT_GROUP will be used.

Throws:

java.lang.IllegalArgumentException - if group is an empty string.

getJobName

public java.lang.String getJobName()

Get the name of the associated JobDetail.

setJobName

public void setJobName(java.lang.String jobName)

Set the name of the associated JobDetail.

Throws:

java.lang.IllegalArgumentException - if jobName is null or empty.

getJobGroup

public java.lang.String getJobGroup()

Get the name of the associated JobDetail's group.

setJobGroup

public void setJobGroup(java.lang.String jobGroup)

Set the name of the associated JobDetail's group.

Parameters:

jobGroup - if null, Scheduler.DEFAULT_GROUP will be used.

Throws:

java.lang.IllegalArgumentException - if group is an empty string.

getFullName

public java.lang.String getFullName()

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

getKey

public Key getKey()

getFullJobName

public java.lang.String getFullJobName()

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

getDescription

public java.lang.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(java.lang.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(java.lang.String calendarName)

Associate the Calendar with the given name with this Trigger.

Parameters:

calendarName - use null to dis-associate a Calendar.

getCalendarName

public java.lang.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(java.lang.String name)

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

removeTriggerListener

public boolean removeTriggerListener(java.lang.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 java.lang.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 java.util.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 java.util.Date getStartTime()

Get the time at which the Trigger should occur.

setStartTime

public abstract void setStartTime(java.util.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(java.util.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 java.util.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 java.util.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 java.util.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 java.util.Date getFireTimeAfter(java.util.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 java.util.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:

java.lang.IllegalStateException - if a required property (such as Name, Group, Class) is not set.

SchedulerException

setFireInstanceId

public void setFireInstanceId(java.lang.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 java.lang.String getFireInstanceId()

This method should not be used by the Quartz client.

toString

public java.lang.String toString()

Return a simple string representation of this object.

Overrides:

toString in class java.lang.Object

compareTo

public int compareTo(java.lang.Object obj)

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

Specified by:

compareTo in interface java.lang.Comparable

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

clone

public java.lang.Object clone()

Overrides:

clone in class java.lang.Object