Class JobChainingJobListener

Namespace

Quartz.Listeners

Assembly

Quartz.dll

Keeps a collection of mappings of which jobs to trigger after the completion of a given job. If this listener is notified of a job completing that has a mapping, then it will then attempt to trigger each of its follow-up jobs. This achieves "job chaining", or a "poor man's workflow".

public sealed class JobChainingJobListener : IJobListener

Inheritance

object

JobChainingJobListener

Implements

IJobListener

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Generally an instance of this listener would be registered as a global job listener, rather than being registered directly to a given job.

A job can be chained to more than one follow-up job, by calling AddJobChainLink(JobKey, JobKey) once per follow-up or AddJobChainLinks(JobKey, IReadOnlyCollection<JobKey>) with all of them. Each follow-up is triggered as its own firing, in the order the links were added, so the follow-ups run concurrently rather than one after another — as many at a time as the thread pool has threads to give them. A follow-up that has to wait for a sibling is a chain link from that sibling, not a second link from the same job.

If for some reason there is a failure creating the trigger for a follow-up job (which would generally only be caused by a rare serious failure in the system, or the non-existence of the follow-up job), an error message is logged, but no other action is taken: the remaining follow-ups of that job are still triggered. If you need more rigorous handling of the error, consider scheduling the triggering of the follow-up job within your job itself.

The links are meant to be registered before the scheduler is started, and this type does not synchronize them; adding one while jobs are executing races with the notifications reading it.

Constructors

JobChainingJobListener(string)

Construct an instance with the given name.

public JobChainingJobListener(string name)

Parameters

name string

The name of this instance.

Properties

Name

The name this listener is registered and removed under.

public string Name { get; }

Property Value

string

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

AddJobChainLink(JobKey, JobKey)

Add a chain mapping - when the Job identified by the first key completes the job identified by the second key will be triggered.

public void AddJobChainLink(JobKey firstJob, JobKey secondJob)

Parameters

firstJob JobKey

a JobKey with the name and group of the first job

secondJob JobKey

a JobKey with the name and group of the follow-up job

Remarks

Calling this again with the same first job adds a second follow-up rather than replacing the first one; the two then run concurrently. Chaining the same follow-up to the same first job twice is a configuration mistake — it would fire that job twice for one completion — and is rejected.

Exceptions

ArgumentException

Either key is null or has a null name, or secondJob is already chained to firstJob.

AddJobChainLinks(JobKey, IReadOnlyCollection<JobKey>)

Add several chain mappings at once - when the Job identified by the first key completes, every one of the given follow-up jobs will be triggered.

public void AddJobChainLinks(JobKey firstJob, IReadOnlyCollection<JobKey> followUpJobs)

Parameters

firstJob JobKey

a JobKey with the name and group of the first job

followUpJobs IReadOnlyCollection<JobKey>

the keys of the jobs to trigger when the first job completes

Remarks

This is AddJobChainLink(JobKey, JobKey) for the fan-out case, and appends to whatever the first job is already chained to. The follow-ups are triggered in the order given, each as its own firing, so they run concurrently. Naming the same follow-up twice — in this collection or against a link added earlier — is a configuration mistake and is rejected; nothing is added when it is.

Exceptions

ArgumentException

Any key is null or has a null name, followUpJobs is null or empty, or a follow-up is named twice.

JobWasExecuted(IJobExecutionContext, JobExecutionException?, CancellationToken)

Called by the IScheduler after a IJobDetail has been executed, and be for the associated IOperableTrigger's Triggered(ICalendar?) method has been called.

public ValueTask JobWasExecuted(IJobExecutionContext context, JobExecutionException? jobException, CancellationToken cancellationToken = default)

Parameters

context IJobExecutionContext

jobException JobExecutionException

cancellationToken CancellationToken

Returns

ValueTask

Remarks

The default implementation does nothing.