Class TriggerBase
The base abstract class to be extended by all triggers.
[Serializable]
public abstract class TriggerBase : IOperableTrigger, IMutableTrigger, ITrigger, IEquatable<TriggerBase>- Inheritance
-
TriggerBase
- Implements
- Derived
- Inherited Members
Remarks
ITriggers have a name and group associated with them, which should uniquely identify them within a single IScheduler.
ITriggers are the 'mechanism' by which IJob s are scheduled. Many ITrigger s can point to the same IJob, but a single ITrigger can only point to one IJob.
Triggers can 'send' parameters/data to IJobs by placing contents into the JobDataMap on the ITrigger.
Constructors
TriggerBase(TimeProvider?)
Create a ITrigger with no specified name, group, or IJobDetail.
protected TriggerBase(TimeProvider? timeProvider = null)Parameters
timeProviderTimeProviderTime provider instance to use, defaults to System
Remarks
Note that Key and JobKey must be set before the ITrigger can be placed into a IScheduler.
Properties
CalendarName
Get or set the ICalendar with the given name with this Trigger. Use null when setting to dis-associate a Calendar.
public virtual string? CalendarName { get; set; }Property Value
Remarks
An empty or whitespace-only name is stored as null. Every job store reads a non-null calendar name as "this trigger observes a calendar" and silently drops the fire when no such calendar exists, so a blank name has to mean no calendar rather than a calendar nothing can find. The value is not trimmed: a calendar is looked up by its exact stored name.
Description
Get or set the description given to the ITrigger instance by its creator (if any).
public virtual string? Description { get; set; }Property Value
EndTimeUtc
Gets and sets the date/time on which the trigger must stop firing. This defines the final boundary for trigger firings 舒 the trigger will not fire after this date and time. If this value is null, no end time boundary is assumed, and the trigger can continue indefinitely.
public virtual DateTimeOffset? EndTimeUtc { get; set; }Property Value
Remarks
The end time is inclusive, for every trigger type: it is the last instant at which the trigger may fire, so a fire time exactly equal to it is one the trigger fires, and the first instant after it is where the schedule stops.
ExecutionGroup
Gets or sets the execution group for this trigger. Execution groups allow thread limits to be configured - per node or across the cluster - so that resource-intensive jobs do not saturate all available threads.
public string? ExecutionGroup { get; set; }Property Value
Remarks
A null value means the trigger has no execution group (the default, backward-compatible behavior).
FinalFireTimeUtc
Returns the last UTC time at which the ITrigger will fire, if the Trigger will repeat indefinitely, null will be returned.
Note that the return time *may* be in the past.
public abstract DateTimeOffset? FinalFireTimeUtc { get; }Property Value
FireInstanceId
The identity of one firing of this trigger, or null if it has not been fired.
public virtual string? FireInstanceId { get; set; }Property Value
Remarks
Written by a job store as it hands the trigger to the scheduler, and read back to recognise the firing when the job completes; it is what InterruptFireInstance(string, CancellationToken) names. A trigger a caller built, and a trigger read back out of a store, have never been fired and answer null — so this is not an identity to key anything on outside the fire path.
HasAdditionalProperties
Gets a value indicating whether this instance has additional properties that should be considered when for example saving to database.
public virtual bool HasAdditionalProperties { get; }Property Value
- bool
trueif this instance has additional properties; otherwise,false.
Remarks
If trigger implementation has additional properties that need to be saved with base properties you need to make your class override this property with value true. Returning true will effectively mean that ADOJobStore needs to serialize this trigger instance to make sure additional properties are also saved.
HasMillisecondPrecision
Whether this trigger's fire times are meaningful to the millisecond. A trigger that says no has its start time rounded down to the second.
protected abstract bool HasMillisecondPrecision { get; }Property Value
Remarks
This is how a trigger describes its own schedule to TriggerBase, not something a caller reads: nothing outside the trigger acted on it.
JobDataMap
Get or set the JobDataMap that is associated with the ITrigger.
Changes made to this map during job execution are not re-persisted, and in fact typically result in an illegal state.
public virtual JobDataMap JobDataMap { get; set; }Property Value
JobKey
Gets or sets the key of the job.
public JobKey JobKey { get; set; }Property Value
- JobKey
The key of the job.
Key
Gets or sets the key of the trigger.
public TriggerKey Key { get; set; }Property Value
- TriggerKey
The key of the trigger.
MayFireAgain
Used by the IScheduler to determine whether or not it is possible for this ITrigger to fire again.
If the returned value is false then the IScheduler may remove the ITrigger from the IJobStore.
public abstract bool MayFireAgain { get; }Property Value
MisfireInstructionCode
Get or set the raw code of the instruction the IScheduler follows when this trigger misses a firing. The concrete trigger type validates the code against its own family's range.
If not explicitly set, the code is zero — "instruction not set" — and the scheduler applies the family's smart policy. The named values are on the per-family enums, such as CronTriggerMisfireInstruction and SimpleTriggerMisfireInstruction.
public virtual int MisfireInstructionCode { get; set; }Property Value
- See Also
NextFireTimeUtc
Returns the next time at which the ITrigger 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).
public abstract DateTimeOffset? NextFireTimeUtc { get; set; }Property Value
Remarks
The value returned is not guaranteed to be valid until after the ITrigger has been added to the scheduler.
The setter should not be used by client code. The scheduler advances this as it fires the trigger; assigning it yourself corrupts the schedule.
PreferredNode
Gets or sets which cluster node this trigger prefers to run on. Only that node acquires the trigger, with automatic failover while it is down.
public PreferredNode PreferredNode { get; set; }Property Value
Remarks
None means the trigger has no node preference (the default, backward-compatible behavior).
The value is recorded as given, automatic-pin flag included, so a pin survives being copied from one trigger to another as the pin it was.
PreviousFireTimeUtc
The previous time at which the ITrigger fired. If the trigger has not yet fired, null will be returned.
public abstract DateTimeOffset? PreviousFireTimeUtc { get; set; }Property Value
Remarks
The setter should not be used by client code. The scheduler records this as it fires the trigger; assigning it yourself corrupts the schedule.
Priority
The priority of a ITrigger acts as a tie breaker such that if two ITriggers 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.
public virtual int Priority { get; set; }Property Value
Remarks
If not explicitly set, the default value is 5.
RetryAttempt
How many times the occurrence currently being executed has already been retried. 0 on
a regular fire.
public int RetryAttempt { get; set; }Property Value
Remarks
The setter should not be used by client code. The scheduler advances it as retries are scheduled and clears it when the occurrence is done with; a job store assigns it when restoring a trigger from its row.
RetryPolicy
Gets or sets how the scheduler re-fires this trigger when its job fails. null — the default — means a failed job is reported and the trigger waits for its next scheduled occurrence.
public RetryPolicy? RetryPolicy { get; set; }Property Value
Remarks
Held as the policy's stored string form, which is what the trigger's row and a serialized trigger both carry; the value is parsed on first read and kept for as long as the string does not change.
- See Also
StartTimeUtc
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.
public virtual DateTimeOffset StartTimeUtc { get; set; }Property Value
Remarks
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.
Methods
Clone()
Creates a new object that is a copy of the current instance.
public virtual ITrigger Clone()Returns
- ITrigger
A new object that is a copy of this instance.
ComputeFirstFireTimeUtc(ICalendar?)
This method should not be used by the Quartz client.
public abstract DateTimeOffset? ComputeFirstFireTimeUtc(ICalendar? calendar)Parameters
calendarICalendar
Returns
- DateTimeOffset?
The first time at which the ITrigger will be fired by the scheduler, which is also the same value NextFireTimeUtc will return (until after the first firing of the ITrigger).
Remarks
Called by the scheduler at the time a ITrigger is first added to the scheduler, in order to have the ITrigger compute its first fire time, based on any associated calendar.
After this method has been called, NextFireTimeUtc should return a valid answer.
Equals(TriggerBase?)
Trigger equality is based upon the equality of the TriggerKey.
public virtual bool Equals(TriggerBase? trigger)Parameters
triggerTriggerBase
Returns
- bool
true if the key of this Trigger equals that of the given Trigger
Equals(object?)
public override bool Equals(object? obj)Parameters
Returns
ExecutionComplete(IJobExecutionContext, JobExecutionException?)
This method should not be used by the Quartz client.
public virtual SchedulerInstruction ExecutionComplete(IJobExecutionContext context, JobExecutionException? result)Parameters
contextIJobExecutionContextis the IJobExecutionContext that was used by the IJob'sExecute(IJobExecutionContext, CancellationToken) method.
resultJobExecutionExceptionis the JobExecutionException thrown by the IJob, if any (may be null).
Returns
- SchedulerInstruction
One of the SchedulerInstruction members.
Remarks
Called after the IScheduler has executed the IJobDetail associated with the ITrigger in order to get the final instruction code from the trigger.
- See Also
GetFireTimeAfter(DateTimeOffset?)
Returns the next time at which the ITrigger will fire, after the given time. If the trigger will not fire after the given time, null will be returned.
public abstract DateTimeOffset? GetFireTimeAfter(DateTimeOffset? afterTime)Parameters
afterTimeDateTimeOffset?
Returns
GetHashCode()
Serves as a hash function for a particular type. GetHashCode() is suitable for use in hashing algorithms and data structures like a hash table.
[SuppressMessage("Sonar", "S3249:Classes directly extending object should not call base in GetHashCode", Justification = "Only reached by a trigger with no key, which equals nothing at all; see the remarks.")]
public override int GetHashCode()Returns
Remarks
The identity hash is for a trigger that has no key yet — one a builder is still assembling, or one deserialized before its key is written back. Equals(TriggerBase?) answers false for every comparison a keyless trigger takes part in, including with itself, so it imposes no obligation on the hash at all; returning a constant instead would put every keyless trigger in one bucket for no gain. Once there is a key, the key is the hash, and that is the case the equality contract is about.
GetScheduleBuilder()
Get a IScheduleBuilder that is configured to produce a schedule identical to this trigger's schedule.
public abstract IScheduleBuilder GetScheduleBuilder()Returns
GetTriggerBuilder()
Get a TriggerBuilder that is configured to produce a trigger identical to this one.
public TriggerBuilder<IJob> GetTriggerBuilder()Returns
Remarks
An interface member where its twin GetJobBuilder(IJobDetail) is an extension, and the asymmetry is the difference between the two rebuilds rather than an unfinished move. A detail's builder can be filled in from the detail's public state alone, so an extension can write it once for every implementation. A trigger's cannot: the builder has to be created against the trigger's own TimeProvider, so that the rebuilt trigger computes its fire times from the same reading of "now" — and a trigger's clock is not part of this interface, because nothing else has any business reading it.
- See Also
RetryFired(ICalendar?)
This method should not be used by the Quartz client.
public virtual void RetryFired(ICalendar? calendar)Parameters
calendarICalendarThe calendar the trigger observes, if any.
Remarks
Called by a job store when it is firing a retry rather than a scheduled occurrence — that is, when the trigger's next fire time is a retry instant ExecutionComplete(IJobExecutionContext, JobExecutionException?) put there. It advances NextFireTimeUtc past the retry to the occurrence the schedule actually calls for, applying the trigger's calendar exactly as Triggered(ICalendar?) does.
Unlike Triggered(ICalendar?) it touches no counter and does not move
PreviousFireTimeUtc: a retry is another attempt at an occurrence that has
already been counted, so it must not burn a repeat count or a recurrence rule's COUNT
slot, and it reports the original occurrence as its scheduled fire time.
- See Also
ToString()
Return a simple string representation of this object.
public override string ToString()Returns
Triggered(ICalendar?)
This method should not be used by the Quartz client.
public abstract void Triggered(ICalendar? calendar)Parameters
calendarICalendar
Remarks
Called when the IScheduler has decided to 'fire' the trigger (Execute the associated IJob), in order to give the ITrigger a chance to update itself for its next triggering (if any).
- See Also
UpdateAfterMisfire(ICalendar?)
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 ITrigger's state according to the misfire instruction the ITrigger was built with, read as MisfireInstructionCode.
public abstract void UpdateAfterMisfire(ICalendar? calendar)Parameters
calendarICalendar
UpdateWithNewCalendar(ICalendar, TimeSpan)
This method should not be used by the Quartz client.
The implementation should update the ITrigger's state based on the given new version of the associated ICalendar (the state should be updated so that it's next fire time is appropriate given the Calendar's new settings).
public abstract void UpdateWithNewCalendar(ICalendar calendar, TimeSpan misfireThreshold)Parameters
Validate()
Validates whether the properties of the IJobDetail are valid for submission into a IScheduler.
public virtual void Validate()ValidateMisfireInstruction(int)
Validates the misfire instruction.
protected abstract bool ValidateMisfireInstruction(int misfireInstruction)Parameters
misfireInstructionintThe misfire instruction.