Class JobExecutionContextBuilder
- Namespace
- Quartz.Extensibility
- Assembly
- Quartz.dll
Builds the execution context a job's Execute(IJobExecutionContext, CancellationToken) is handed, so that a job can be called directly — in a unit test, most usually — without a scheduler firing it.
public sealed class JobExecutionContextBuilder- Inheritance
-
JobExecutionContextBuilder
- Inherited Members
Remarks
JobExecutionContextBuilder.For(job).WithJob(detail).WithTrigger(trigger).FiredAt(when).Build()
builds the context Quartz itself builds, a JobExecutionContextImpl, and every part of
that chain but For<TJob>(TJob) and Build() can be left out.
What is left out is what a firing would have: a job detail of the job's own type, a trigger that fires once for it, fired now and on time, not recovering, never retried or refired, with no calendar and a token nothing cancels but an interrupt. The previous fire time is the trigger's own and the next is the one its schedule gives after this firing, skipping what the calendar excludes, as a job store reports them. There is no scheduler unless WithScheduler(IScheduler) gives one, so a job that uses Scheduler needs one — a fake is enough.
"Now" and JobRunTime are read from System unless WithTimeProvider(TimeProvider) gives another clock. The scheduler is not asked for its clock: a faked scheduler answers with a faked one. The run begins when the context is built.
The trigger is copied before it is used, as a job store copies the trigger it fires, so the trigger passed to WithTrigger(ITrigger) is not changed by the fire-instance id, the input, the retry attempt or the recovery data the context is given, and one builder can build any number of independent contexts.
Methods
Build()
Builds the context. Each call builds a new one, over a new copy of the trigger.
public JobExecutionContextImpl Build()Returns
Remarks
The context owns a CancellationTokenSource once its token has been read, or from the start when WithCancellation(CancellationToken) gave a token, so dispose it when the job has run.
FiredAt(DateTimeOffset, DateTimeOffset?)
Sets when the trigger fired and, for a late firing, when it was due.
public JobExecutionContextBuilder FiredAt(DateTimeOffset fireTimeUtc, DateTimeOffset? scheduledFireTimeUtc = null)Parameters
fireTimeUtcDateTimeOffsetWhat FireTimeUtc answers.
scheduledFireTimeUtcDateTimeOffset?What ScheduledFireTimeUtc answers. Left out, the firing was on time and it is
fireTimeUtc.
Returns
For<TJob>(TJob)
Starts a context for one execution of job.
public static JobExecutionContextBuilder For<TJob>(TJob job) where TJob : IJobParameters
jobTJobThe instance whose Execute(IJobExecutionContext, CancellationToken) the context is for.
Returns
Type Parameters
TJobThe job's type, which the default job detail is made for.
Remarks
Generic so that the job detail made when WithJob(IJobDetail) is not called names the job's type without reflecting over the instance, which a trimmed application could not do.
Recovering(bool)
Sets whether the firing recovers an execution a failed scheduler left behind, which is what Recovering answers.
public JobExecutionContextBuilder Recovering(bool recovering = true)Parameters
Returns
Remarks
A recovering context's trigger carries what a job store's recovery trigger carries: the FailedJobOriginalTriggerName and FailedJobOriginalTriggerGroup of the trigger it stands for, which RecoveringTriggerKey reads, and that firing's fire times as FailedJobOriginalTriggerFireTime and FailedJobOriginalTriggerScheduledFireTime. The trigger stands for itself, fired at the times this context reports. A trigger whose job data already names an original trigger keeps all four as it has them.
- See Also
WithCalendar(ICalendar)
Sets the calendar the trigger fires against, which is what Calendar answers.
public JobExecutionContextBuilder WithCalendar(ICalendar calendar)Parameters
calendarICalendarThe calendar, which is used as it is and not copied.
Returns
Remarks
NextFireTimeUtc skips the times it excludes, as a trigger's Triggered(ICalendar?) does. The trigger's CalendarName is left as it is.
WithCancellation(CancellationToken)
Sets a token that cancels CancellationToken, so a test can cancel the job it runs.
public JobExecutionContextBuilder WithCancellation(CancellationToken cancellationToken)Parameters
cancellationTokenCancellationTokenThe token that cancels the firing.
Returns
Remarks
The context's token is linked to it rather than being it: cancelling this token cancels the context's, and an interrupt cancels the context's and leaves this one alone. Hand the job CancellationToken, as the scheduler does, so the token Execute(IJobExecutionContext, CancellationToken) is given cancels too.
WithInput<TInput>(TInput)
Sets the input the firing carries, which an IJob<TInput> is handed and GetInput<TInput>(IJobExecutionContext) reads.
public JobExecutionContextBuilder WithInput<TInput>(TInput input)Parameters
inputTInputThe payload.
Returns
Type Parameters
TInputThe type the job reads the input as.
Remarks
It is put on the copy of the trigger, so it wins over an input on the job detail, as a trigger's input does when a scheduler fires it. It is stored as the value itself rather than serialized, which is how a job reads it back without an IJobInputSerializer.
WithJob(IJobDetail)
Sets the job detail the context carries: its key, its job data, its flags.
public JobExecutionContextBuilder WithJob(IJobDetail jobDetail)Parameters
jobDetailIJobDetailThe job detail, which is used as it is and not copied.
Returns
WithRefireCount(int)
Sets how many times the job has already been re-run within this firing, which is what RefireCount answers.
public JobExecutionContextBuilder WithRefireCount(int refireCount)Parameters
refireCountint0on the first run,non then-th refire.
Returns
Remarks
A refire is the in-process loop a JobExecutionException with RefireImmediately asks for, not a retry.
Exceptions
- ArgumentOutOfRangeException
refireCountis negative.
WithRetryAttempt(int)
Sets how many times the occurrence has already been retried, which is what RetryAttempt answers.
public JobExecutionContextBuilder WithRetryAttempt(int retryAttempt)Parameters
retryAttemptint0on a regular fire,non then-th retry.
Returns
Remarks
It is written to the copy of the trigger, where a job store writes it and where the context reads
it. The last attempt is the one whose count equals the policy's
MaxAttempts; give the trigger or the job type a policy for
RetryPolicy to answer one. Left out, the trigger's own count
stands, which is 0 for a trigger that has never been retried.
Exceptions
- ArgumentOutOfRangeException
retryAttemptis negative.
WithScheduler(IScheduler)
Sets what Scheduler answers.
public JobExecutionContextBuilder WithScheduler(IScheduler scheduler)Parameters
schedulerISchedulerThe scheduler, usually a fake one.
Returns
WithTimeProvider(TimeProvider)
Sets the clock the context is built on: the default fire time is its "now", and JobRunTime is measured on it from the moment the context is built.
public JobExecutionContextBuilder WithTimeProvider(TimeProvider timeProvider)Parameters
timeProviderTimeProviderThe clock, usually the one the scheduler under test is given.
Returns
Remarks
Pass the FakeTimeProvider a test drives, so JobRunTime
advances by exactly what the test advances it by. The default trigger is built on it too.
WithTrigger(ITrigger)
Sets the trigger that fired, whose job data overrides the job detail's in MergedJobDataMap.
public JobExecutionContextBuilder WithTrigger(ITrigger trigger)Parameters
triggerITriggerThe trigger, which is copied when the context is built.
Returns
Exceptions
- ArgumentException
triggeris not an IOperableTrigger, which every trigger a job store fires is.