Interface ITriggerListener
- Namespace
- Quartz
- Assembly
- Quartz.dll
The interface to be implemented by classes that want to be informed when a ITrigger fires. In general, applications that use a IScheduler will not have use for this mechanism.
public interface ITriggerListenerRemarks
Every callback leads with the ITrigger it is about, and every callback is told which scheduler is calling it: a listener reaches the scheduler it serves through its execution context, or as a second argument when there is no execution. Only TriggerMisfired(ITrigger, IScheduler, CancellationToken) is of the second kind — a misfire is noticed rather than executed, so it has no context to carry one.
Every member has a default implementation, so an implementation only has to write the notifications it cares about. Name defaults to the implementing type's name.
Properties
Name
The name this listener is registered and removed under.
string Name { get; }Property Value
Remarks
Defaults to the implementing type's name, which is the right answer whenever a scheduler has at most one listener of a given type. Override it when several instances of one type are registered with the same scheduler, because the later registration would otherwise replace the earlier one.
Methods
TriggerComplete(ITrigger, IJobExecutionContext, SchedulerInstruction, CancellationToken)
Called by the IScheduler when a ITrigger has fired, it's associated IJobDetail has been executed, and it's Triggered(ICalendar?) method has been called.
ValueTask TriggerComplete(ITrigger trigger, IJobExecutionContext context, SchedulerInstruction triggerInstructionCode, CancellationToken cancellationToken = default)Parameters
triggerITriggerThe ITrigger that was fired.
contextIJobExecutionContextThe IJobExecutionContext that was passed to the IJob'sExecute(IJobExecutionContext, CancellationToken) method.
triggerInstructionCodeSchedulerInstructionThe result of the call on the ITrigger'sTriggered(ICalendar?) method.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
Remarks
The default implementation does nothing.
TriggerFired(ITrigger, IJobExecutionContext, CancellationToken)
Called by the IScheduler when a ITrigger has fired, and it's associated IJobDetail is about to be executed.
It is called before the VetoJobExecution(ITrigger, IJobExecutionContext, CancellationToken) method of this interface.
ValueTask TriggerFired(ITrigger trigger, IJobExecutionContext context, CancellationToken cancellationToken = default)Parameters
triggerITriggerThe ITrigger that has fired.
contextIJobExecutionContextThe IJobExecutionContext that will be passed to the IJob'sExecute(IJobExecutionContext, CancellationToken) method.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
Remarks
The default implementation does nothing.
TriggerMisfired(ITrigger, IScheduler, CancellationToken)
Called by the IScheduler when a ITrigger has misfired.
Consideration should be given to how much time is spent in this method, as it will affect all triggers that are misfiring. If you have lots of triggers misfiring at once, it could be an issue it this method does a lot.
ValueTask TriggerMisfired(ITrigger trigger, IScheduler scheduler, CancellationToken cancellationToken = default)Parameters
triggerITriggerThe ITrigger that has misfired.
schedulerISchedulerThe scheduler raising the notification.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
Remarks
The scheduler is passed because a misfire is noticed outside any execution, so there is no IJobExecutionContext here to reach it through. It comes after the trigger, as the context does on every other notification in this interface.
The default implementation does nothing.
TriggerRetriesExhausted(ITrigger, IJobExecutionContext, JobExecutionException, CancellationToken)
Called by the IScheduler when a failed occurrence under a retry policy is over without another attempt: a RetryPolicy applies — the trigger's own, its job type's or the scheduler's default — the job ran and threw, and the firing did not end in a retry.
ValueTask TriggerRetriesExhausted(ITrigger trigger, IJobExecutionContext context, JobExecutionException exception, CancellationToken cancellationToken = default)Parameters
triggerITriggerThe ITrigger whose occurrence has given up.
contextIJobExecutionContextThe IJobExecutionContext of the last attempt. RetryAttempt is how many retries that occurrence had already spent, and RetryScheduled is false.
exceptionJobExecutionExceptionWhat the last attempt threw.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
Remarks
Raised once per failed occurrence that is not going to be retried, whichever of these is why:
- the policy's attempts are spent — the case the name describes;
- a retry was declined for lack of room: it would have landed at, or within a second of, the trigger's next scheduled occurrence, after its EndTimeUtc, or past the end of representable time — attempts may be left, but there is nowhere to make one;
- the job's JobExecutionException asked for UnscheduleFiringTrigger or UnscheduleAllTriggers, a directive that wins over the policy, so no retry is attempted whatever the policy has left.
It comes between JobWasExecuted(IJobExecutionContext, JobExecutionException?, CancellationToken) and TriggerComplete(ITrigger, IJobExecutionContext, SchedulerInstruction, CancellationToken). It is never raised for a failure the trigger answered with another attempt — that firing's instruction is RetryTrigger — nor for a firing that was cancelled, vetoed or succeeded, nor for a trigger with no retry policy: nothing gave up, because nothing was going to try again. RefireImmediately re-runs the job inside the same firing, so only the run that ends the firing can raise it.
Giving up is not an error. The trigger goes back to its ordinary schedule with its attempt cleared — unless the job asked for it to be unscheduled — which is why this notification exists: without it the only way to tell "retrying" from "given up" was to compare TriggerComplete(ITrigger, IJobExecutionContext, SchedulerInstruction, CancellationToken)'s instruction against RetryTrigger and know what the trigger's policy said.
The default implementation does nothing.
TriggerSkipped(ITrigger, IScheduler, CancellationToken)
Called by the IScheduler when a firing of a ITrigger whose OverlapPolicy is Skip came due while an earlier firing of it was still running, and was dropped.
ValueTask TriggerSkipped(ITrigger trigger, IScheduler scheduler, CancellationToken cancellationToken = default)Parameters
triggerITriggerThe trigger, as it was when the firing was dropped: NextFireTimeUtc is the firing that did not happen.
schedulerISchedulerThe scheduler raising the notification.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
Remarks
A skipped firing is not a misfire: TriggerMisfired(ITrigger, IScheduler, CancellationToken) is not called for it, and the trigger's misfire instruction is not applied. The scheduler is passed for the reason it is passed to TriggerMisfired(ITrigger, IScheduler, CancellationToken): nothing ran, so there is no execution context.
The default implementation does nothing.
VetoJobExecution(ITrigger, IJobExecutionContext, CancellationToken)
Called by the IScheduler when a ITrigger has fired, and it's associated IJobDetail is about to be executed.
It is called after the TriggerFired(ITrigger, IJobExecutionContext, CancellationToken) method of this interface. If the implementation vetoes the execution (via returning true), the job's execute method will not be called.
ValueTask<bool> VetoJobExecution(ITrigger trigger, IJobExecutionContext context, CancellationToken cancellationToken = default)Parameters
triggerITriggerThe ITrigger that has fired.
contextIJobExecutionContextThe IJobExecutionContext that will be passed to the IJob'sExecute(IJobExecutionContext, CancellationToken) method.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
Remarks
The default implementation vetoes nothing.