Class StdAdoDelegate

Namespace: Quartz.Impl.AdoJobStore

Assembly: Quartz.dll

This is meant to be an abstract base class for most, if not all, IDriverDelegate implementations. Subclasses should override only those methods that need special handling for the DBMS driver in question.

public class StdAdoDelegate : IDriverDelegate, IDbAccessor

Inheritance: object

StdAdoDelegate

Implements: IDriverDelegate

IDbAccessor

Derived: FirebirdDelegate

MySQLDelegate

OracleDelegate

PostgreSQLDelegate

SQLiteDelegate

SqlServerDelegate

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Internal, as the progress statement is: they are issued only by this store's own RequestInterrupt, GetInterruptRequests and CancelPrevious fire, every one is portable across the dialects, and keeping them off IDriverDelegate leaves a delegate written outside Quartz nothing to implement.

Properties

AdditionalLikeWildcards

The characters this dialect treats as LIKE wildcards beyond % and _, which every dialect has. Empty for all but the T-SQL family.

protected virtual string AdditionalLikeWildcards { get; }

Property Value

string

Remarks

SQL Server and Sybase read [ as the start of a character class, so an unescaped ?nameContains=[a-z] matches by class there and literally everywhere else. It cannot be escaped unconditionally: the standard says an escape character must be followed by a wildcard or itself, and PostgreSQL enforces that, so ![ is an error on a dialect where [ is not a wildcard.

CanUseProperties

Whether job data is stored as a name-value table of strings rather than as a serialized map.

protected virtual bool CanUseProperties { get; }

Property Value

bool

Remarks

The store's StoreJobDataAsStrings setting. A store that has written blobs cannot be switched to strings without rewriting them, which is why this is read rather than decided here.

DbProvider

The database this delegate reads and writes through.

protected IDbProvider DbProvider { get; }

Property Value

IDbProvider

FiltersAcquisitionExecutionGroups

Whether SelectTriggersToAcquire(ConnectionAndTransactionHolder, TriggerAcquisitionCriteria, CancellationToken) already keeps the rows outside ServedExecutionGroups — or inside RefusedExecutionGroups — out of what it returns.

public virtual bool FiltersAcquisitionExecutionGroups { get; }

Property Value

bool

Remarks

The same contract as FiltersAcquisitionJobTypeExclusions, for the same reason: a delegate that ignores the routing would have the node run a group the deployment gave to other nodes. So the ADO store keeps a backstop — it drops a candidate the node does not serve, ordinally on ExecutionGroup, before reading it back — and this says the backstop has nothing left to do.

false by default, because a delegate written before routing existed cannot have honoured it. StdAdoDelegate answers true, and so does every dialect Quartz ships. A delegate of somebody's own that replaces the acquisition statement without the clause must answer false.

FiltersAcquisitionJobTypeExclusions

Whether SelectTriggersToAcquire(ConnectionAndTransactionHolder, TriggerAcquisitionCriteria, CancellationToken) already keeps ExcludedJobTypeNames out of the rows it returns.

public virtual bool FiltersAcquisitionJobTypeExclusions { get; }

Property Value

bool

Remarks

Every other property of TriggerAcquisitionCriteria may be ignored by a delegate with no worse consequence than a wider result than asked for. This one is different: ignoring it means the node runs job types the deployment excluded. So the ADO store keeps a backstop — it drops an excluded candidate ordinally on JobTypeName before reading the trigger back — and this property is how a delegate says the backstop has nothing left to do.

It defaults to false, because a delegate written before the exclusions existed cannot have honoured them. StdAdoDelegate answers true: its acquisition statement carries the NOT IN clause, and every dialect Quartz ships builds its statement from that one. A delegate of somebody's own that replaces the acquisition statement without the clause — or overrides StdAdoDelegate.GetSelectNextTriggerToAcquireSql to drop it — must answer false, or the exclusions stop being enforced anywhere.

SchedulerName

The name of the scheduler this delegate serves, which every statement here is scoped by.

protected string SchedulerName { get; }

Property Value

string

Remarks

A dialect delegate that writes a statement of its own rather than adjusting one of the base class's needs the same value, and the base class already has it: without this it would have to override Initialize(DriverDelegateContext) to keep a second copy from DriverDelegateContext.

A property over the field rather than the field turned into an auto-property, so that the hundred statements below go on reading schedulerName and this stays one added line.

SchemaResourceName

The embedded script that creates this dialect's schema, or null when this delegate has none.

protected virtual string? SchemaResourceName { get; }

Property Value

string

Remarks

Null on StdAdoDelegate itself, because there is no dialect-neutral DDL: the six shipped delegates each name their own script, and a delegate written outside Quartz names one or leaves provisioning unavailable. Overriding it is the whole of what a delegate has to do to support CreateIfMissing.

The name is a manifest resource name, looked for in the assembly of the delegate's own type and then in each assembly up its base chain. So a delegate of somebody else's can embed a script of its own beside itself, and one that subclasses a shipped dialect delegate to change a statement or two inherits that dialect's script rather than having to carry a copy.

SupportsFireOnAcquire

Whether the store may fire a trigger in the transaction that acquires it through this delegate's round members, in place of its single-trigger ones.

public virtual bool SupportsFireOnAcquire { get; }

Property Value

bool

Remarks

A default interface member answering false, so a delegate written against an earlier 4.x has every one of its members called as before. Its round is still one transaction, but each trigger is claimed and reserved, its header and job read, and its fire written as an update of that reservation, through the single-trigger members, exactly as acquiring and then firing it did. StdAdoDelegate answers true for the delegates Quartz ships and false for a subclass; a subclass whose overrides the round members cover may answer true.

Methods

AddCommandParameter(DbCommand, string, object?, Enum?, int?)

Adds a parameter to IDbCommand.

public virtual void AddCommandParameter(DbCommand cmd, string paramName, object? paramValue, Enum? dataType = null, int? size = null)

Parameters

cmd DbCommand: Command to add parameter to
paramName string: Parameter's name
paramValue object: Parameter's value
dataType Enum: Parameter's data type
size int?: Parameter's optional size

AddDefaultTriggerPersistenceDelegates()

Registers the persistence delegates for the five trigger families Quartz ships.

protected virtual void AddDefaultTriggerPersistenceDelegates()

Remarks

Called before the delegates a container supplied, so those override a built-in one by declaring the same discriminator.

AddExecutionGroupParameters(DbCommand, ExecutionGroupClauseShape, IReadOnlyCollection<ExecutionGroupScope>?)

Binds the routed groups' parameters — @servedGroup0000… or @refusedGroup0000…, in the order the clause numbers them — after the statement's own parameters, for providers that bind positionally. Nothing is bound for a shape with no clause.

protected void AddExecutionGroupParameters(DbCommand cmd, ExecutionGroupClauseShape shape, IReadOnlyCollection<ExecutionGroupScope>? groups)

Parameters

cmd DbCommand: The command carrying a clause of shape.
shape ExecutionGroupClauseShape: The clause's shape, whose list decides the parameter prefix.
groups IReadOnlyCollection<ExecutionGroupScope>: The scopes the clause names; the default bucket among them binds nothing.

AddPagingParameters(DbCommand, int, int, bool)

Binds the parameters of the clause ApplyPaging(string, bool) appended.

protected virtual void AddPagingParameters(DbCommand cmd, int skip, int take, bool takeLimited)

Parameters

cmd DbCommand: The command to bind.
skip int: Rows to skip.
take int: Rows to read: one more than the page size, so that the extra row tells the caller whether anything follows the page.
takeLimited bool: Whether the page has an upper bound.

AddPreferredNodeParameters(DbCommand, DateTimeOffset)

Binds the preferred node (node affinity) parameters of the acquisition SQL. Parameters are added in SQL token order for providers with positional binding.

protected void AddPreferredNodeParameters(DbCommand cmd, DateTimeOffset liveNodeCutoff)

Parameters

cmd DbCommand: The acquisition command.
liveNodeCutoff DateTimeOffset: Instant before which a node's last check-in is considered stale, releasing its pinned triggers to other nodes. Bound through GetDbDateTimeValue(DateTimeOffset?), so the raw ticks the liveness SQL compares stay inside this binder.

AddTriggerPersistenceDelegate(ITriggerPersistenceDelegate)

Registers a persistence delegate, initialising it with this delegate's scheduler name, table prefix and value binding.

public virtual void AddTriggerPersistenceDelegate(ITriggerPersistenceDelegate persistenceDelegate)

Parameters

persistenceDelegate ITriggerPersistenceDelegate: The delegate to register.

Remarks

The first registration of a discriminator wins, and the built-in delegates are registered first, so a delegate of one's own overrides a built-in family only by being registered before them.

ApplyPaging(string, bool)

Appends the dialect's paging clause to a statement that already carries its ORDER BY.

protected virtual string ApplyPaging(string sql, bool takeLimited)

Parameters

sql string: The statement to page.
takeLimited bool: Whether the page has an upper bound. When false the caller only wants to skip, and the clause must not limit the row count.

Returns

string

Remarks

The default is the ANSI form, understood by SQL Server 2012+, Oracle 12c+, PostgreSQL and Firebird 3+. Both bounds are bound as parameters, so one statement text serves every page. A delegate overriding this must override AddPagingParameters(DbCommand, int, int, bool) as well when its clause names the two parameters in the other order — providers that bind positionally take parameters in the order the statement mentions them.

ApplyTriggerFired(ConnectionAndTransactionHolder, TriggerFiredUpdate, CancellationToken)

Apply every row change one trigger fire makes.

public virtual ValueTask ApplyTriggerFired(ConnectionAndTransactionHolder conn, TriggerFiredUpdate update, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
update TriggerFiredUpdate: The changes the fire makes.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

The fire path has read everything it decides on before it writes anything, so what is left is a run of writes with no read between them: the fired-trigger row, the misfire original fire time where one was recorded, the sibling triggers of a job that disallows concurrent execution, the trigger's own row, and its schedule in whichever type table holds it. They go out as one DbBatch where the provider supports batching, and one command at a time where it does not.

All of it is one transaction either way, and a batch executes its commands in sequence, so the order the writes were issued in is the order they still happen in.

ApplyTriggersFired(ConnectionAndTransactionHolder, IReadOnlyList<TriggerFiredUpdate>, CancellationToken)

Apply every row change the fires of one acquisition round make.

public virtual ValueTask ApplyTriggersFired(ConnectionAndTransactionHolder conn, IReadOnlyList<TriggerFiredUpdate> updates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
updates IReadOnlyList<TriggerFiredUpdate>: The changes each fire makes, in the order the round fired them.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

The plural of ApplyTriggerFired(ConnectionAndTransactionHolder, TriggerFiredUpdate, CancellationToken), for an acquisition that fires what is due in the same transaction (#3864): the round decides every fire before it writes any, so the writes of all of them can go together. StdAdoDelegate sends them as one DbBatch where the provider can batch. The writes of one fire keep their order, and the fires keep the order given. Called only for a delegate that answers SupportsFireOnAcquire with true.

A default interface member, so a delegate written against an earlier 4.x keeps working: the default is ApplyTriggerFired(ConnectionAndTransactionHolder, TriggerFiredUpdate, CancellationToken) for each update, in order, and tells the store which update failed, so that it rolls back that fire alone. An override cannot tell it — the exception that carries the position is internal — so a failure out of an override makes the store roll the round back and run it again one trigger at a time, through ApplyTriggerFired(ConnectionAndTransactionHolder, TriggerFiredUpdate, CancellationToken), which finds the fire that failed.

CalendarExists(ConnectionAndTransactionHolder, string, CancellationToken)

Check whether or not a calendar exists.

public virtual ValueTask<bool> CalendarExists(ConnectionAndTransactionHolder conn, string calendarName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
calendarName string: The name of the calendar.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>: true if the trigger exists, false otherwise.

CalendarIsReferenced(ConnectionAndTransactionHolder, string, CancellationToken)

Check whether or not a calendar is referenced by any triggers.

public virtual ValueTask<bool> CalendarIsReferenced(ConnectionAndTransactionHolder conn, string calendarName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
calendarName string: The name of the calendar.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>: true if any triggers reference the calendar, false otherwise

ClearData(ConnectionAndTransactionHolder, CancellationToken)

Clear (delete!) all scheduling data - all IJobs, ITriggers ICalendars.

public virtual ValueTask ClearData(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder
cancellationToken CancellationToken

Returns

ValueTask

Remarks

One delete per table, which used to be one round trip and one undisposed command each. They go out as one batch where the provider supports batching, and one disposed command at a time where it does not. The order matters and the batch preserves it: a batch executes its commands in sequence.

ClearMisfireOriginalFireTime(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Clears the misfire original fire time for the given trigger.

public virtual ValueTask ClearMisfireOriginalFireTime(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder
triggerKey TriggerKey
cancellationToken CancellationToken

Returns

ValueTask

Remarks

The fire path clears it as one command of ApplyTriggerFired(ConnectionAndTransactionHolder, TriggerFiredUpdate, CancellationToken)'s batch rather than through this, so overriding this alone no longer changes what a fire clears.

ClearTriggerPauses(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, CancellationToken)

Forgets the pause recorded on the given triggers, which a resume does.

public virtual ValueTask ClearTriggerPauses(ConnectionAndTransactionHolder conn, IReadOnlyCollection<TriggerKey> triggerKeys, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKeys IReadOnlyCollection<TriggerKey>: The triggers resumed. An empty collection does nothing.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

Called after the resume's own statements, which are unchanged, for the triggers they moved. A trigger with no record is left as it is. A default interface member; the default forgets nothing, having recorded nothing.

ClearTriggerRetryAttempt(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Puts a trigger's retry attempt back to zero, leaving everything else about the row alone.

public virtual ValueTask<int> ClearTriggerRetryAttempt(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
triggerKey TriggerKey: The trigger to clear.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: How many rows were updated.

Remarks

The other end of UpdateTriggerForRetry(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, CancellationToken): the occurrence is done with, whether it succeeded or spent its attempts. Issued only when the attempt was actually non-zero, so an ordinary completion still costs no extra statement.

ConvertFromProperty(NameValueCollection)

Convert the stored properties into the entries of a JobDataMap.

protected virtual Dictionary<string, object?> ConvertFromProperty(NameValueCollection properties)

Parameters

properties NameValueCollection

Returns

Dictionary<string, object>

ConvertToProperty(IDictionary<string, object?>)

Convert the JobDataMap into a list of properties.

protected virtual NameValueCollection ConvertToProperty(IDictionary<string, object?> data)

Parameters

data IDictionary<string, object>

Returns

NameValueCollection

CountMisfiredTriggersInState(ConnectionAndTransactionHolder, StoredTriggerState, DateTimeOffset, CancellationToken)

Counts the triggers in the given state that missed their scheduled fire time.

public virtual ValueTask<int> CountMisfiredTriggersInState(ConnectionAndTransactionHolder conn, StoredTriggerState state, DateTimeOffset misfireTime, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
state StoredTriggerState: The trigger state to scan.
misfireTime DateTimeOffset: Triggers with no threshold of their own whose next fire time is at or before this are misfired: now less the store's MisfireThreshold. A trigger with a MISFIRE_THRESHOLD of its own is misfired once its next fire time is at or before now less that, now being the delegate's TimeProvider (#4070).
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>

CountTriggersForJob(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Select the number of triggers associated with a given job.

public virtual ValueTask<int> CountTriggersForJob(ConnectionAndTransactionHolder conn, JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of triggers for the given job

CreateSchema(ConnectionAndTransactionHolder, CancellationToken)

Creates whatever this delegate's schema is missing, and leaves everything that is already there exactly as it is.

public virtual ValueTask CreateSchema(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

Called at startup, before ValidateSchema(ConnectionAndTransactionHolder, CancellationToken), when CreateIfMissing is configured. Every statement it runs is guarded, so this is a no-op against a schema that already exists; nothing is altered and nothing is dropped, which is what makes it safe to leave on and what keeps a mis-typed table prefix from costing data.

It is not a migration. A schema that has every table but is missing a column a later release added is left exactly as it is; upgrading a schema is what database/migrations/ is for. For that reason the store will not call this at all against a schema 4.x did not create — creating the tables a 3.x schema is missing would leave one that starts and fires nothing — so a delegate's script only ever meets a database whose Quartz tables, if it has any, this version made.

A delegate that has no script for its database throws rather than pretending to have created anything, naming itself and the script to run by hand.

Exceptions

JobPersistenceException: A statement failed, or this delegate has no schema script.

DeleteBlobTrigger(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Delete the BLOB trigger data for a trigger.

public virtual ValueTask<int> DeleteBlobTrigger(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows deleted

DeleteCalendar(ConnectionAndTransactionHolder, string, CancellationToken)

Delete a calendar.

public virtual ValueTask<int> DeleteCalendar(ConnectionAndTransactionHolder conn, string calendarName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
calendarName string: The name of the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows deleted.

DeleteFiredTrigger(ConnectionAndTransactionHolder, string, CancellationToken)

Delete a fired trigger.

public virtual ValueTask<int> DeleteFiredTrigger(ConnectionAndTransactionHolder conn, string entryId, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
entryId string: The fired trigger entry to delete.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows deleted.

DeleteFiredTriggers(ConnectionAndTransactionHolder, FiredTriggerQuery, CancellationToken)

Deletes the fired triggers the query selects. A query with no filter set deletes all of them.

public virtual ValueTask<int> DeleteFiredTriggers(ConnectionAndTransactionHolder conn, FiredTriggerQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
query FiredTriggerQuery: Which fired triggers to delete.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows deleted

DeleteFiredTriggers(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken)

Delete several fired triggers by entry id, in as few round trips as the provider allows.

public virtual ValueTask DeleteFiredTriggers(ConnectionAndTransactionHolder conn, IReadOnlyCollection<string> entryIds, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
entryIds IReadOnlyCollection<string>: The fired trigger entries to delete. An empty collection does nothing.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

The same statement as the single-entry overload, once per id, issued as one DbBatch where the provider supports batching. This is the shape cluster recovery needs when it is clearing a dead node's rows but holding some of them back: the whole-instance DeleteFiredTriggers(ConnectionAndTransactionHolder, FiredTriggerQuery, CancellationToken) would take the preserved rows with it. No row count comes back, for the reason UpdateTriggerStatesForJobsFromOtherState(ConnectionAndTransactionHolder, IReadOnlyCollection<JobKey>, StoredTriggerState, StoredTriggerState, CancellationToken) gives.

DeleteJobDetail(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Delete the job detail record for the given job.

public virtual ValueTask<int> DeleteJobDetail(ConnectionAndTransactionHolder conn, JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows deleted

DeletePausedJobGroup(ConnectionAndTransactionHolder, GroupMatcher<JobKey>, CancellationToken)

Deletes the paused job groups the matcher selects. A single group is GroupEquals(string).

public virtual ValueTask<int> DeletePausedJobGroup(ConnectionAndTransactionHolder conn, GroupMatcher<JobKey> matcher, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The database connection.
matcher GroupMatcher<JobKey>: Criteria for matching groups.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows deleted.

DeletePausedTriggerGroup(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, CancellationToken)

Deletes the paused trigger groups the matcher selects. A single group is GroupEquals(string).

public virtual ValueTask<int> DeletePausedTriggerGroup(ConnectionAndTransactionHolder conn, GroupMatcher<TriggerKey> matcher, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The database connection.
matcher GroupMatcher<TriggerKey>: Criteria for matching groups.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>

DeleteSchedulerState(ConnectionAndTransactionHolder, string, CancellationToken)

Delete a scheduler-instance state record.

public virtual ValueTask<int> DeleteSchedulerState(ConnectionAndTransactionHolder conn, string instanceId, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
instanceId string: The instance id.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of deleted rows.

DeleteTrigger(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Delete the base trigger data for a trigger.

public virtual ValueTask<int> DeleteTrigger(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows deleted

DeleteTriggerExtension(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Deletes whatever the registered persistence delegates hold for a trigger, beside its row in the triggers table.

protected virtual ValueTask DeleteTriggerExtension(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The unit of work.
triggerKey TriggerKey: The trigger being deleted.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

Stops at the first delegate that deleted a row: a trigger belongs to one family, so no second delegate has anything of its own to remove.

EscapeSqlLikeWildcards(string)

Escapes the LIKE wildcards '%' and '_', and the escape character '!' itself, so that the value matches literally.

protected static string EscapeSqlLikeWildcards(string value)

Parameters

value string

Returns

string

EscapeSqlLikeWildcards(string, string)

Escapes the LIKE wildcards '%' and '_', the escape character '!' itself, and any character of additionalWildcards, so that the value matches literally.

protected static string EscapeSqlLikeWildcards(string value, string additionalWildcards)

Parameters

value string: The text to match literally.
additionalWildcards string: What else the dialect reads as a wildcard — see AdditionalLikeWildcards.

Returns

string

FindTriggerPersistenceDelegate(IOperableTrigger)

The registered delegate that handles trigger's family, or null when none does — which is what makes a trigger stored as a blob.

protected virtual ITriggerPersistenceDelegate? FindTriggerPersistenceDelegate(IOperableTrigger trigger)

Parameters

trigger IOperableTrigger: The trigger being written.

Returns

ITriggerPersistenceDelegate

FindTriggerPersistenceDelegate(string)

The registered delegate that reads the given trigger-type discriminator back, or null when none does.

protected virtual ITriggerPersistenceDelegate? FindTriggerPersistenceDelegate(string discriminator)

Parameters

discriminator string: The value read from the trigger's type column.

Returns

ITriggerPersistenceDelegate

GetBooleanFromDbValue(object)

Gets the boolean value from db presentation. Subclasses can overwrite this behaviour.

public virtual bool GetBooleanFromDbValue(object columnValue)

Parameters

columnValue object: Value to map from database.

Returns

bool

GetCountMisfiredTriggersInStateSql()

The statement counting the triggers in the given states that have misfired.

protected virtual string GetCountMisfiredTriggersInStateSql()

Returns

string

GetDateTimeFromDbValue(object)

Gets the date/time value from db presentation. The storage format is part of the schema contract; see GetDbDateTimeValue(DateTimeOffset?).

public DateTimeOffset? GetDateTimeFromDbValue(object columnValue)

Parameters

columnValue object: Value to map from database.

Returns

DateTimeOffset?

GetDbBooleanValue(bool)

Gets the db presentation for boolean value. Subclasses can overwrite this behaviour.

public virtual object GetDbBooleanValue(bool booleanValue)

Parameters

booleanValue bool: Value to map to database.

Returns

object

GetDbDateTimeValue(DateTimeOffset?)

Gets the db presentation for date/time value: UTC ticks. The storage format is part of the schema contract, not an extension point — the preferred-node liveness SQL compares raw check-in values assuming it, so a delegate cannot change how instants are stored without owning its SQL outright.

public object? GetDbDateTimeValue(DateTimeOffset? dateTimeValue)

Parameters

dateTimeValue DateTimeOffset?: Value to map to database.

Returns

object

GetDbTimeSpanValue(TimeSpan?)

Gets the db presentation for time span value: whole milliseconds. The storage format is part of the schema contract, not an extension point — the preferred-node liveness SQL multiplies stored check-in intervals assuming it, so a delegate cannot change how durations are stored without owning its SQL outright.

public object? GetDbTimeSpanValue(TimeSpan? timeSpanValue)

Parameters

timeSpanValue TimeSpan?: Value to map to database.

Returns

object

GetJobDataFromBlob<T>(DbDataReader, int, CancellationToken)

This method should be overridden by any delegate subclasses that need special handling for BLOBs for job details.

protected virtual ValueTask<T?> GetJobDataFromBlob<T>(DbDataReader rs, int colIndex, CancellationToken cancellationToken = default) where T : class

Parameters

rs DbDataReader: The result set, already queued to the correct row.
colIndex int: The column index for the BLOB.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<T>: The deserialized Object from the ResultSet BLOB.

Type Parameters

T

GetKeyOfNonSerializableValue(JobDataMap)

The key of the first value in data the serializer cannot write, or null when every value round-trips.

protected object? GetKeyOfNonSerializableValue(JobDataMap data)

Parameters

data JobDataMap: The map being stored.

Returns

object

Remarks

Used to name the offending entry in the failure, rather than reporting that a job data map somewhere could not be stored.

GetObjectFromBlob<T>(DbDataReader, int, CancellationToken)

This method should be overridden by any delegate subclasses that need special handling for BLOBs. The default implementation uses standard ADO.NET operations.

protected virtual ValueTask<T?> GetObjectFromBlob<T>(DbDataReader rs, int colIndex, CancellationToken cancellationToken = default) where T : class

Parameters

rs DbDataReader: The data reader, already queued to the correct row.
colIndex int: The column index for the BLOB.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<T>: The deserialized object from the DataReader BLOB.

Type Parameters

T

GetRowLimit(int)

Where this dialect's row-limiting clause goes, and what it says. The one thing a dialect has to declare in order to limit a row-limited statement: both statements that carry a limit ask here, so a dialect says it once and neither statement is rewritten by hand.

protected virtual SqlRowLimit GetRowLimit(int count)

Parameters

count int: The most rows the statement may return, always at least one.

Returns

SqlRowLimit

Remarks

The default limits nothing, because there is no ANSI way to. The sentinel that asks for no limit at all is dealt with before this is called, so an override never sees it.

GetSelectMisfiredTriggersToRecoverSql(int)

The statement selecting the misfired triggers to recover, limited to count rows.

protected virtual string GetSelectMisfiredTriggersToRecoverSql(int count)

Parameters

count int: The most rows to read, or no limit.

Returns

string

Remarks

The row limit is expressed through GetRowLimit, which is the member a dialect overrides; overriding this one is for a dialect whose whole statement differs.

GetSelectNextTriggerToAcquireSql(TriggerAcquisitionSqlShape)

Builds the acquisition statement for one shape. A dialect that overrides this and stops splicing in ExcludedJobTypeBucket terms must also override FiltersAcquisitionJobTypeExclusions to false, so that the store's backstop takes over; one that drops the ExecutionGroups clause must do the same with FiltersAcquisitionExecutionGroups.

protected virtual string GetSelectNextTriggerToAcquireSql(TriggerAcquisitionSqlShape shape)

Parameters

shape TriggerAcquisitionSqlShape

Returns

string

GetTimeSpanFromDbValue(object)

Gets the time span value from db presentation. The storage format is part of the schema contract; see GetDbTimeSpanValue(TimeSpan?).

public TimeSpan? GetTimeSpanFromDbValue(object columnValue)

Parameters

columnValue object: Value to map from database.

Returns

TimeSpan?

Initialize(DriverDelegateContext)

Initializes the driver delegate.

public virtual void Initialize(DriverDelegateContext context)

Parameters

context DriverDelegateContext

InsertBlobTrigger(ConnectionAndTransactionHolder, IOperableTrigger, CancellationToken)

Insert the blob trigger data.

public virtual ValueTask<int> InsertBlobTrigger(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
trigger IOperableTrigger: The trigger to insert
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows inserted

InsertCalendar(ConnectionAndTransactionHolder, string, ICalendar, CancellationToken)

Insert a new calendar.

public virtual ValueTask<int> InsertCalendar(ConnectionAndTransactionHolder conn, string calendarName, ICalendar calendar, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
calendarName string: The name for the new calendar.
calendar ICalendar: The calendar.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows inserted.

InsertFiredTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, IJobDetail?, CancellationToken)

Insert a fired trigger.

public virtual ValueTask<int> InsertFiredTrigger(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, StoredTriggerState state, IJobDetail? job, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
trigger IOperableTrigger: The trigger.
state StoredTriggerState: The state that the trigger should be stored in.
job IJobDetail
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows inserted.

InsertFiredTriggers(ConnectionAndTransactionHolder, IReadOnlyList<IOperableTrigger>, StoredTriggerState, IJobDetail?, CancellationToken)

Inserts the fired-trigger rows of one acquisition round in as few round trips as the provider allows.

public virtual ValueTask InsertFiredTriggers(ConnectionAndTransactionHolder conn, IReadOnlyList<IOperableTrigger> triggers, StoredTriggerState state, IJobDetail? jobDetail, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
triggers IReadOnlyList<IOperableTrigger>: The triggers to record, in the order they were acquired.
state StoredTriggerState: The state that the triggers should be stored in.
jobDetail IJobDetail: The job detail, or null when no job is named yet.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

The rows are all in the same state and belong to the same job detail, which is what an acquisition round produces: every row goes in as Acquired with no job named yet. The default implementation is the loop the store used to make itself, so a delegate that says nothing about batching keeps behaving exactly as it did.

InsertJobDetail(ConnectionAndTransactionHolder, IJobDetail, CancellationToken)

Insert the job detail record.

public virtual ValueTask<int> InsertJobDetail(ConnectionAndTransactionHolder conn, IJobDetail job, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder
job IJobDetail
cancellationToken CancellationToken

Returns

ValueTask<int>: Number of rows inserted.

InsertJobGroupPauses(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, PauseInfo, CancellationToken)

Records that each of the given job groups is paused, and why.

public virtual ValueTask InsertJobGroupPauses(ConnectionAndTransactionHolder conn, IReadOnlyCollection<string> groupNames, PauseInfo pause, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
groupNames IReadOnlyCollection<string>: The groups to pause. May be empty.
pause PauseInfo: What to record on each.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

InsertPausedJobGroups(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken) with the record. A default interface member; the default calls InsertPausedJobGroups(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken).

InsertPausedJobGroup(ConnectionAndTransactionHolder, string, CancellationToken)

Records that a job group is paused.

public virtual ValueTask<int> InsertPausedJobGroup(ConnectionAndTransactionHolder conn, string groupName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The database connection.
groupName string: Name of the group.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows inserted.

Remarks

The row is what makes the pause outlive the process and reach the other nodes of a cluster, and what a caller adding a job to the group later reads. The table's primary key rejects a duplicate, so callers check first — under the trigger-access lock, which is what keeps two nodes pausing the same group from racing.

InsertPausedJobGroups(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken)

Writes a paused row for each of the given job groups, in as few round trips as the provider allows.

public virtual ValueTask InsertPausedJobGroups(ConnectionAndTransactionHolder conn, IReadOnlyCollection<string> groupNames, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The database connection.
groupNames IReadOnlyCollection<string>: The groups to pause. May be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

Every group is expected to have no row yet — the caller established that with SelectPausedJobGroups(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken) under the same lock — so this is a plain insert per group rather than an upsert. The default implementation issues them one at a time.

InsertPausedTriggerGroup(ConnectionAndTransactionHolder, string, CancellationToken)

Inserts the paused trigger group.

public virtual ValueTask<int> InsertPausedTriggerGroup(ConnectionAndTransactionHolder conn, string groupName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The conn.
groupName string: Name of the group.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>

InsertSchedulerState(ConnectionAndTransactionHolder, string, DateTimeOffset, TimeSpan, CancellationToken)

Insert a scheduler-instance state record.

public virtual ValueTask<int> InsertSchedulerState(ConnectionAndTransactionHolder conn, string instanceId, DateTimeOffset checkInTime, TimeSpan interval, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
instanceId string: The instance id.
checkInTime DateTimeOffset: The check in time.
interval TimeSpan: The interval.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of inserted rows.

InsertTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, IJobDetail, CancellationToken)

Insert the base trigger data.

public virtual ValueTask<int> InsertTrigger(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, StoredTriggerState state, IJobDetail jobDetail, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
trigger IOperableTrigger: The trigger to insert.
state StoredTriggerState: The state that the trigger should be stored in.
jobDetail IJobDetail: The job detail.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows inserted

InsertTriggerGroupPause(ConnectionAndTransactionHolder, string, PauseInfo, CancellationToken)

Records that a trigger group is paused, and why.

public virtual ValueTask<int> InsertTriggerGroupPause(ConnectionAndTransactionHolder conn, string groupName, PauseInfo pause, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
groupName string: Name of the group.
pause PauseInfo: What to record.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows inserted.

Remarks

InsertPausedTriggerGroup(ConnectionAndTransactionHolder, string, CancellationToken) with the record. A default interface member; the default calls InsertPausedTriggerGroup(ConnectionAndTransactionHolder, string, CancellationToken).

IsJobCurrentlyExecuting(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Checks whether a job is currently being executed (has a fired trigger in EXECUTING state). Used to enforce DisallowConcurrentExecutionAttribute across cluster nodes.

public virtual ValueTask<bool> IsJobCurrentlyExecuting(ConnectionAndTransactionHolder conn, JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>

IsJobGroupPaused(ConnectionAndTransactionHolder, string, CancellationToken)

Determines whether the specified job group is paused.

public virtual ValueTask<bool> IsJobGroupPaused(ConnectionAndTransactionHolder conn, string groupName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The database connection.
groupName string: Name of the group.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>: true if the job group is paused; otherwise, false.

IsMatcherEquals<T>(StringMatcher<T>)

Whether matcher is an exact-match one, which becomes = rather than LIKE.

protected static bool IsMatcherEquals<T>(StringMatcher<T> matcher) where T : Key<T>

Parameters

matcher StringMatcher<T>: The matcher being translated.

Returns

bool

Type Parameters

T

IsTriggerCurrentlyExecuting(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Checks whether a trigger has a firing in EXECUTING state, on any node. Used by a trigger's OverlapPolicy across cluster nodes.

public virtual ValueTask<bool> IsTriggerCurrentlyExecuting(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>

Remarks

A default interface member, so a delegate written against an earlier 4.x keeps compiling. The default reads the trigger's fired rows through SelectFiredTriggerRecords(ConnectionAndTransactionHolder, FiredTriggerQuery, CancellationToken); StdAdoDelegate counts them instead.

IsTriggerGroupPaused(ConnectionAndTransactionHolder, string, CancellationToken)

Determines whether the specified trigger group is paused.

public virtual ValueTask<bool> IsTriggerGroupPaused(ConnectionAndTransactionHolder conn, string groupName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The conn.
groupName string: Name of the group.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>: true if trigger group is paused; otherwise, false.

JobExists(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Check whether or not the given job exists.

public virtual ValueTask<bool> JobExists(ConnectionAndTransactionHolder conn, JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>: true if the job exists, false otherwise

MatchGroup<T>(GroupMatcher<T>, string, string)

Picks the statement a group matcher should run and the value to bind for it: an equality matcher gets the '=' form, everything else the LIKE form over the pattern the matcher translates to.

protected (string Sql, string Parameter) MatchGroup<T>(GroupMatcher<T> matcher, string equalsSql, string likeSql) where T : Key<T>

Parameters

matcher GroupMatcher<T>
equalsSql string
likeSql string

Returns

(string Sql, string Parameter)

Type Parameters

T

Remarks

The equality form is not merely a shortcut — LIKE would treat a group whose name contains '%' or '_' as a pattern, and it cannot use an index the way '=' can.

PauseTriggerGroupStates(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, PauseInfo, CancellationToken)

Moves every trigger of the matching groups that is in one of oldStates to newState, recording pause on each row it moves.

public virtual ValueTask<int> PauseTriggerGroupStates(ConnectionAndTransactionHolder conn, GroupMatcher<TriggerKey> matcher, StoredTriggerState newState, IReadOnlyCollection<StoredTriggerState> oldStates, PauseInfo pause, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
matcher GroupMatcher<TriggerKey>: The groups whose triggers to pause.
newState StoredTriggerState: The paused state to move them to.
oldStates IReadOnlyCollection<StoredTriggerState>: The states a trigger must be in to be moved. Must not be empty.
pause PauseInfo: What to record on each row moved.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows moved.

Remarks

The pause form of UpdateTriggerGroupStateFromOtherStates(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, CancellationToken). A default interface member; the default moves the rows and records nothing.

PauseTriggerStates(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, PauseInfo, CancellationToken)

Moves the given triggers that are in one of oldStates to newState, recording pause on each row it moves.

public virtual ValueTask<int> PauseTriggerStates(ConnectionAndTransactionHolder conn, IReadOnlyCollection<TriggerKey> triggerKeys, StoredTriggerState newState, IReadOnlyCollection<StoredTriggerState> oldStates, PauseInfo pause, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKeys IReadOnlyCollection<TriggerKey>: The triggers to pause.
newState StoredTriggerState: The paused state to move them to.
oldStates IReadOnlyCollection<StoredTriggerState>: The states a trigger must be in to be moved. Must not be empty.
pause PauseInfo: What to record on each row moved.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows moved.

Remarks

The pause form of UpdateTriggerStatesFromOtherStates(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, CancellationToken), in one statement so a row is never paused without its record. A default interface member, so a delegate written against an earlier 4.x keeps compiling; the default moves the rows and records nothing.

PrepareCommand(ConnectionAndTransactionHolder, string)

Prepares a IDbCommand to be used to access database.

public virtual DbCommand PrepareCommand(ConnectionAndTransactionHolder cth, string commandText)

Parameters

cth ConnectionAndTransactionHolder: Connection and transaction pair
commandText string: SQL to run

Returns

DbCommand

ReadBytesFromBlob(DbDataReader, int, CancellationToken)

Reads a BLOB column as bytes. Overridden by a delegate whose driver needs special handling for large objects.

protected virtual ValueTask<byte[]?> ReadBytesFromBlob(DbDataReader rs, int colIndex, CancellationToken cancellationToken = default)

Parameters

rs DbDataReader: The data reader, already queued to the correct row.
colIndex int: The column index for the BLOB.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<byte[]>

Remarks

This was the last member of the ADO.NET surface still speaking the legacy IDataReader. Every reader the store hands it is a DbDataReader, and the synchronous interface meant this one read blocked its thread and ignored the cancellation token it was handed.

It also read the column twice — once with a null buffer to learn the length, once to fill it — which is a documented GetBytes(int, long, byte[], int, int) idiom but two trips through the provider's blob handling. GetFieldValueAsync<T>(int, CancellationToken) asks for the whole value once and lets the provider size it.

ReleaseContinuation(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, DateTimeOffset, CancellationToken)

Moves one awaiting trigger into the ordinary schedule, firing at fireTime, and clears the continuation columns: a released trigger is an ordinary one and waits for nothing.

public virtual ValueTask<int> ReleaseContinuation(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, StoredTriggerState newState, DateTimeOffset fireTime, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
triggerKey TriggerKey: The awaiting trigger to release.
newState StoredTriggerState: The state to release it into — the one a trigger stored at this moment would get: waiting, paused if its group is, blocked if its job disallows concurrent execution and is running.
fireTime DateTimeOffset: When the released trigger fires, as the store worked it out: the later of now and the trigger's start time, moved on to its calendar's next included instant when the calendar excludes that one. A continuation whose end time is behind that instant is discarded rather than released, so this is never past the trigger's end time.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: How many rows were updated.

Remarks

Only a row still in Awaiting is written, which is what makes settlement one-shot. A default interface member for the reason SelectAwaitingContinuations(ConnectionAndTransactionHolder, TriggerKey, CancellationToken) is one, but this default refuses: it is only ever reached for a continuation that member found, so a delegate that answers that one and not this one is half-implemented rather than merely old.

RepinTriggersFromDeadNode(ConnectionAndTransactionHolder, string, string, CancellationToken)

Releases all auto-claimed pins belonging to a dead node back to the given value (batch UPDATE). Explicit pins are left untouched. Used during ClusterRecover to implement sticky failover.

public virtual ValueTask<int> RepinTriggersFromDeadNode(ConnectionAndTransactionHolder conn, string oldPreferredNode, string newPreferredNode, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder
oldPreferredNode string
newPreferredNode string
cancellationToken CancellationToken

Returns

ValueTask<int>

ReplaceTablePrefix(string)

Replace the table prefix in a query by replacing any occurrences of "{0}" with the table prefix.

protected string ReplaceTablePrefix(string query)

Parameters

query string: The unsubstituted query

Returns

string: The query, with proper table prefix substituted

ResetContinuationFireTime(ConnectionAndTransactionHolder, TriggerKey, DateTimeOffset, CancellationToken)

Gives a continuation that has just been reset out of the error state a fire time, and clears its continuation columns, the same way ReleaseContinuation(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, DateTimeOffset, CancellationToken) does.

public virtual ValueTask<int> ResetContinuationFireTime(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, DateTimeOffset now, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
triggerKey TriggerKey: The trigger that was just reset.
now DateTimeOffset: The scheduler's reading of "now", which the fire time is floored at.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: How many rows were updated.

Remarks

Touches only a row that names a parent — in the error state, a continuation parked because its parent was deleted, since a released one names none — so an ordinary trigger's reset costs a statement that matches nothing. A default interface member that does nothing: a delegate with no continuation columns has no such row to fix.

SelectAwaitingContinuations(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

The triggers waiting, in Awaiting, for one trigger's firing — and the condition each of them waits on.

public virtual ValueTask<List<AwaitingContinuation>> SelectAwaitingContinuations(ConnectionAndTransactionHolder conn, TriggerKey parent, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
parent TriggerKey: The trigger whose firing the returned triggers are waiting for.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<AwaitingContinuation>>

Remarks

A default interface member, added in 4.2: a delegate written against an earlier 4.x reports nothing rather than failing every completion, which is the truth for it — a delegate that does not write the continuation columns never has a row to find. The default is the reason the other two members below can afford to refuse.

SelectCalendar(ConnectionAndTransactionHolder, string, CancellationToken)

Select a calendar.

public virtual ValueTask<ICalendar?> SelectCalendar(ConnectionAndTransactionHolder conn, string calendarName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
calendarName string: The name of the calendar.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<ICalendar>: The Calendar.

SelectCalendarNames(ConnectionAndTransactionHolder, CalendarQuery, CancellationToken)

Selects one page of calendar names, ordered by name.

public virtual ValueTask<PagedResult<string>> SelectCalendarNames(ConnectionAndTransactionHolder conn, CalendarQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
query CalendarQuery: Which names to select and which page of them to return.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PagedResult<string>>

SelectExecutionGroupsInFlight(ConnectionAndTransactionHolder, CancellationToken)

Counts what the cluster currently holds in flight for each (execution group, trigger group) pair, which is what a Cluster execution limit is counted against.

public virtual ValueTask<List<ExecutionGroupInFlight>> SelectExecutionGroupsInFlight(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<ExecutionGroupInFlight>>: One entry per distinct pair with work in flight; empty when the cluster is idle.

Remarks

The answer is an aggregate over the fired-triggers table, whose rows already have exactly the lifetime a reservation needs: written when a trigger is acquired, updated when it fires, deleted when it completes or when cluster recovery cleans up after the node that owned it. So the count includes a peer's reservation that has not started yet, and a dead node's rows keep holding slots until recovery clears them — under-serving the quota rather than over-serving it, which is the safe direction.

Both group names are returned because the limits derive their key from the pair; see ExecutionGroupInFlight. Rows are bounded by the distinct pairs currently in flight, not by the size of the schedule.

SelectFireInstances(ConnectionAndTransactionHolder, FireInstanceQuery, CancellationToken)

Selects one page of fire instances, ordered by trigger group, then trigger name, then entry id.

public virtual ValueTask<PagedResult<FireInstance>> SelectFireInstances(ConnectionAndTransactionHolder conn, FireInstanceQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
query FireInstanceQuery: What to select and which page of it to return.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PagedResult<FireInstance>>

Remarks

The listing reads the FIRED_TRIGGERS row only, and only the columns FireInstance projects — not the concurrency and recovery flags that SelectFiredTriggerRecords(ConnectionAndTransactionHolder, FiredTriggerQuery, CancellationToken) reads for the recovery passes. The entry id is part of the ordering because trigger group and name do not identify a row here: one trigger can have several firings at once.

SelectFiredTriggerInstanceNames(ConnectionAndTransactionHolder, CancellationToken)

Select the distinct instance names of all fired-trigger records.

public virtual ValueTask<List<string>> SelectFiredTriggerInstanceNames(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The conn.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<string>>

Remarks

This is useful when trying to identify orphaned fired triggers (a fired trigger without a scheduler state record.)

SelectFiredTriggerRecords(ConnectionAndTransactionHolder, FiredTriggerQuery, CancellationToken)

Selects the states of the fired-trigger records the query selects. A query with no filter set selects all of them.

public virtual ValueTask<List<FiredTriggerRecord>> SelectFiredTriggerRecords(ConnectionAndTransactionHolder conn, FiredTriggerQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
query FiredTriggerQuery: Which fired triggers to select.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<FiredTriggerRecord>>: A list of FiredTriggerRecord objects.

Remarks

Not a listing — SelectFireInstances(ConnectionAndTransactionHolder, FireInstanceQuery, CancellationToken) is. This one is the whole set, every column, for the maintenance passes that have to see all of it.

SelectJobDetail(ConnectionAndTransactionHolder, JobKey, ITypeLoader, CancellationToken)

Select the JobDetail object for a given job name / group name.

public virtual ValueTask<IJobDetail?> SelectJobDetail(ConnectionAndTransactionHolder conn, JobKey jobKey, ITypeLoader typeLoader, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
typeLoader ITypeLoader: The type loader.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<IJobDetail>: The populated JobDetail object

SelectJobDetails(ConnectionAndTransactionHolder, IReadOnlyCollection<JobKey>, ITypeLoader, CancellationToken)

Selects several jobs at once, chunking the keys into as few statements as the provider's parameter ceiling allows. Keys that have no row are simply absent from the result.

public virtual ValueTask<List<IJobDetail>> SelectJobDetails(ConnectionAndTransactionHolder conn, IReadOnlyCollection<JobKey> jobKeys, ITypeLoader typeLoader, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
jobKeys IReadOnlyCollection<JobKey>: The keys of the jobs to select.
typeLoader ITypeLoader: The type loader.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<IJobDetail>>

SelectJobForTrigger(ConnectionAndTransactionHolder, TriggerKey, ITypeLoader, bool, CancellationToken)

Select the job to which the trigger is associated.

public virtual ValueTask<IJobDetail?> SelectJobForTrigger(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, ITypeLoader typeLoader, bool loadJobType, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
triggerKey TriggerKey: The key identifying the trigger.
typeLoader ITypeLoader: The type loader.
loadJobType bool: Whether to resolve the job's type now, which throws when the class is not in this process. false gets a job detail whose JobType is the recorded name, resolved lazily by whoever comes to run it. It says nothing about the job's two attribute flags: ConcurrentExecutionDisallowed and PersistJobDataAfterExecution come from IS_NONCONCURRENT and IS_UPDATE_DATA either way, so a caller deciding whether a trigger is blocked does not need the class to decide it correctly.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<IJobDetail>

SelectJobGroupPause(ConnectionAndTransactionHolder, string, CancellationToken)

The pause recorded on a paused job group's row, or null when there is no row or it recorded nothing.

public virtual ValueTask<PauseInfo?> SelectJobGroupPause(ConnectionAndTransactionHolder conn, string groupName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
groupName string: The job group to ask about.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PauseInfo>

Remarks

A default interface member, whose default answers null.

SelectJobGroups(ConnectionAndTransactionHolder, JobGroupQuery, CancellationToken)

Selects one page of job groups, ordered by name.

public virtual ValueTask<PagedResult<JobGroup>> SelectJobGroups(ConnectionAndTransactionHolder conn, JobGroupQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
query JobGroupQuery: What to select and which page of it to return.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PagedResult<JobGroup>>

Remarks

A query for paused groups only reads PAUSED_JOB_GRPS, so it reports a paused group that currently holds no jobs as well. That table has no counterpart to AllGroupsPaused: pause-all is a trigger operation and writes no marker row here.

SelectJobHeaders(ConnectionAndTransactionHolder, JobQuery, CancellationToken)

Selects one page of job listing entries, ordered by group and then name.

public virtual ValueTask<PagedResult<JobHeader>> SelectJobHeaders(ConnectionAndTransactionHolder conn, JobQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
query JobQuery: What to select and which page of it to return.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PagedResult<JobHeader>>

Remarks

The listing does not read or deserialize JOB_DATA, and does not load the job type — the header carries the recorded type name as a string.

SelectJobKeysInGroup(ConnectionAndTransactionHolder, GroupMatcher<JobKey>, CancellationToken)

Select all of the jobs contained in a given group.

public virtual ValueTask<List<JobKey>> SelectJobKeysInGroup(ConnectionAndTransactionHolder conn, GroupMatcher<JobKey> matcher, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
matcher GroupMatcher<JobKey>: Which groups to read, or every group when it matches anything.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<JobKey>>: An array of string job names.

SelectMisfiredTriggersToRecover(ConnectionAndTransactionHolder, StoredTriggerState, DateTimeOffset, int, CancellationToken)

Selects the misfired triggers to recover as fully populated triggers, rather than as keys that the caller then has to read back one at a time. Same predicate and ordering as CountMisfiredTriggersInState(ConnectionAndTransactionHolder, StoredTriggerState, DateTimeOffset, CancellationToken).

public virtual ValueTask<MisfiredTriggerBatch> SelectMisfiredTriggersToRecover(ConnectionAndTransactionHolder conn, StoredTriggerState state, DateTimeOffset misfireTime, int count, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
state StoredTriggerState: The trigger state to scan (Waiting).
misfireTime DateTimeOffset: Triggers with no threshold of their own whose next fire time is at or before this are misfired: now less the store's MisfireThreshold. A trigger with a MISFIRE_THRESHOLD of its own is misfired once its next fire time is at or before now less that, now being the delegate's TimeProvider (#4070).
count int: Maximum number of triggers to return, or -1 for all of them.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<MisfiredTriggerBatch>

SelectPausedJobGroups(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken)

Of the given job groups, which already have a paused row.

public virtual ValueTask<List<string>> SelectPausedJobGroups(ConnectionAndTransactionHolder conn, IReadOnlyCollection<string> groupNames, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The database connection.
groupNames IReadOnlyCollection<string>: The groups to ask about. May be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<string>>: The subset of groupNames that is paused.

Remarks

The set form of IsJobGroupPaused(ConnectionAndTransactionHolder, string, CancellationToken), which is what pausing a matcher's worth of job groups actually asks: it needs the groups that do not have a row, so that it can write exactly those. The default implementation asks one group at a time, as that path used to.

SelectSchedulerNames(ConnectionAndTransactionHolder, CancellationToken)

Every scheduler name this database holds anything under, in no particular order.

public virtual ValueTask<List<string>> SelectSchedulerNames(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<string>>: The distinct SCHED_NAME values in this database.

Remarks

The one member here that is not about the scheduler the delegate was initialized for: it answers which schedulers there are, which is what a dashboard pointed at a database needs before it can have a scheduler name to ask anything else with. A name is reported when the database holds a check-in row, a trigger or a job detail under it — no one of those alone is enough, since a scheduler that is not clustered writes no check-in row and one whose jobs are durable and unscheduled has no triggers.

The default implementation refuses rather than answering, because there is nothing here it could answer with: every other member of this interface is scoped to one scheduler's rows, so a delegate that does not implement this has no cross-scheduler statement to borrow. StdAdoDelegate implements it in dialect-neutral SQL, so a delegate derived from it — which is every delegate Quartz ships and every one its documentation teaches — has it already.

Exceptions

NotSupportedException: This delegate cannot discover scheduler names.

SelectSchedulerStateRecords(ConnectionAndTransactionHolder, string?, CancellationToken)

A List of all current SchedulerStateRecords.

If instanceId is not null, then only the record for the identified instance will be returned.

public virtual ValueTask<List<SchedulerStateRecord>> SelectSchedulerStateRecords(ConnectionAndTransactionHolder conn, string? instanceId, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
instanceId string: The instance id, or null for every instance.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<SchedulerStateRecord>>

SelectStoredTriggerHeaders(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, CancellationToken)

Selects the stored headers of a whole set of triggers, chunking the keys into as few statements as the provider's parameter ceiling allows. Keys that have no row are simply absent from the result.

public virtual ValueTask<List<StoredTriggerHeader>> SelectStoredTriggerHeaders(ConnectionAndTransactionHolder conn, IReadOnlyCollection<TriggerKey> triggerKeys, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKeys IReadOnlyCollection<TriggerKey>: The keys identifying the triggers. May be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<StoredTriggerHeader>>

Remarks

The plural of SelectTriggerHeader(ConnectionAndTransactionHolder, TriggerKey, CancellationToken) — the storage-side header a state transition decides on, not the listing entry SelectTriggerHeaders(ConnectionAndTransactionHolder, TriggerQuery, CancellationToken) pages over. Pause and resume read one of these per key and then decide the whole set's transitions at once; the default implementation is the per-key loop they used to make.

SelectTrigger(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Select a trigger.

public virtual ValueTask<IOperableTrigger?> SelectTrigger(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<IOperableTrigger>: The ITrigger object.

SelectTriggerGroupNames(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, CancellationToken)

Select all trigger group names a group matcher selects. Pass AnyGroup() for every group.

public virtual ValueTask<List<string>> SelectTriggerGroupNames(ConnectionAndTransactionHolder conn, GroupMatcher<TriggerKey> matcher, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
matcher GroupMatcher<TriggerKey>: The matcher to apply for searching.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<string>>: The names of the matching groups.

Remarks

Not a listing — SelectTriggerGroups(ConnectionAndTransactionHolder, TriggerGroupQuery, CancellationToken) with a TriggerGroupQuery is. This one serves the pause/resume mutation paths, which need every matching group in one go so that they can update them under the same lock, and which therefore must not be paged.

SelectTriggerGroupPause(ConnectionAndTransactionHolder, string, CancellationToken)

The pause recorded on a paused trigger group's row, or null when there is no row or it recorded nothing.

public virtual ValueTask<PauseInfo?> SelectTriggerGroupPause(ConnectionAndTransactionHolder conn, string groupName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
groupName string: The trigger group to ask about.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PauseInfo>

Remarks

A default interface member, whose default answers null.

SelectTriggerGroups(ConnectionAndTransactionHolder, TriggerGroupQuery, CancellationToken)

Selects one page of trigger groups, ordered by name.

public virtual ValueTask<PagedResult<TriggerGroup>> SelectTriggerGroups(ConnectionAndTransactionHolder conn, TriggerGroupQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
query TriggerGroupQuery: What to select and which page of it to return.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PagedResult<TriggerGroup>>

Remarks

A query for paused groups only reads PAUSED_TRIGGER_GRPS, so it reports a paused group that currently has no triggers as well. It must not report AllGroupsPaused: that row records "everything is paused" and is not a group any trigger can belong to.

SelectTriggerHeader(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Select the stored state, next fire time and job of one trigger, in a single statement.

public virtual ValueTask<StoredTriggerHeader?> SelectTriggerHeader(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<StoredTriggerHeader>: The trigger's header, or null when no such trigger exists.

SelectTriggerHeaders(ConnectionAndTransactionHolder, TriggerQuery, CancellationToken)

Selects one page of trigger listing entries, ordered by group and then name.

public virtual ValueTask<PagedResult<TriggerHeader>> SelectTriggerHeaders(ConnectionAndTransactionHolder conn, TriggerQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
query TriggerQuery: What to select and which page of it to return.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PagedResult<TriggerHeader>>

Remarks

The listing reads the TRIGGERS row only: no type table, no BLOB, no JOB_DATA.

SelectTriggerJobDataMap(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Select a trigger's JobDataMap.

public virtual ValueTask<JobDataMap> SelectTriggerJobDataMap(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<JobDataMap>: The JobDataMap of the Trigger, never null, but possibly empty.

SelectTriggerKeysForJob(ConnectionAndTransactionHolder, JobKey, StoredTriggerState, CancellationToken)

Get the keys of the triggers of the given job that are in the given state.

public virtual ValueTask<List<TriggerKey>> SelectTriggerKeysForJob(ConnectionAndTransactionHolder conn, JobKey jobKey, StoredTriggerState state, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
state StoredTriggerState: The state the triggers must be in.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>

Remarks

The filtered form of the overload above, for the callers that want the state rather than the trigger — completion bookkeeping asking which of a job's triggers it has just unblocked, where loading each trigger and then asking the database for its state one at a time is a read per trigger for an answer one read can give.

SelectTriggerKeysForJob(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Get the keys of all the triggers associated with the given job.

public virtual ValueTask<List<TriggerKey>> SelectTriggerKeysForJob(ConnectionAndTransactionHolder conn, JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>

Remarks

Not a listing — SelectTriggerHeaders(ConnectionAndTransactionHolder, TriggerQuery, CancellationToken) with a job filter is. This one serves the pause/resume and removal mutation paths, which need every key of the job in one go so that they can update them under the same lock, and which therefore must not be paged.

SelectTriggerKeysForJobs(ConnectionAndTransactionHolder, IReadOnlyCollection<JobKey>, CancellationToken)

Get the keys of every trigger belonging to any of the given jobs.

public virtual ValueTask<List<TriggerKey>> SelectTriggerKeysForJobs(ConnectionAndTransactionHolder conn, IReadOnlyCollection<JobKey> jobKeys, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKeys IReadOnlyCollection<JobKey>: The keys identifying the jobs. May be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>

Remarks

The job-set form of the first overload above, for pausing and resuming a whole matcher's worth of jobs: what those paths want is one flat set of trigger keys, and reading it a job at a time is a statement per job for an answer one statement can give. The default implementation is that per-job loop.

SelectTriggerKeysInGroup(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, CancellationToken)

Select the keys of all the triggers a group matcher selects.

public virtual ValueTask<List<TriggerKey>> SelectTriggerKeysInGroup(ConnectionAndTransactionHolder conn, GroupMatcher<TriggerKey> matcher, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
matcher GroupMatcher<TriggerKey>: Criteria for matching groups.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>: The keys of the matching triggers.

Remarks

Not a listing — SelectTriggerHeaders(ConnectionAndTransactionHolder, TriggerQuery, CancellationToken) is. This one serves the pause/resume mutation paths, which need every matching key in one go so that they can update them under the same lock, and which therefore must not be paged.

SelectTriggerKeysInState(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, StoredTriggerState, CancellationToken)

Select which of the given triggers are in the given state.

public virtual ValueTask<List<TriggerKey>> SelectTriggerKeysInState(ConnectionAndTransactionHolder conn, IReadOnlyCollection<TriggerKey> triggerKeys, StoredTriggerState state, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKeys IReadOnlyCollection<TriggerKey>: The keys to ask about.
state StoredTriggerState: The state the triggers must be in.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>: The keys of those triggers that are in the state.

Remarks

The set-taking form of SelectTriggerState(ConnectionAndTransactionHolder, TriggerKey, CancellationToken), for a caller that already holds the keys — cluster recovery asking which of a failed node's triggers ran to COMPLETE, where a state per key is a round trip per key for an answer one read gives. A key with no row, or with a row in another state, is simply absent from the result.

SelectTriggerPause(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

The pause recorded for a trigger that is paused: its own record, or its trigger group's — the pause-all marker's, for a group row written with no record of its own — or its job group's.

public virtual ValueTask<PauseInfo?> SelectTriggerPause(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKey TriggerKey: The trigger to ask about.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PauseInfo>

Remarks

null for a trigger that is missing or not PAUSED or PAUSED_BLOCKED — so a record a node that does not record pauses left behind when it resumed the trigger is never read — and for one whose pause recorded nothing. A default interface member, whose default answers null.

SelectTriggerState(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Select a trigger's state value.

public virtual ValueTask<StoredTriggerState> SelectTriggerState(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<StoredTriggerState>: The trigger's stored state, or Deleted when no such trigger exists.

SelectTriggerStateWithExecuting(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Selects a trigger's stored state together with whether it currently has an execution in flight.

public virtual ValueTask<TriggerExecutionState> SelectTriggerStateWithExecuting(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder
triggerKey TriggerKey
cancellationToken CancellationToken

Returns

ValueTask<TriggerExecutionState>: The trigger's state and execution, or NotFound when no such trigger exists.

SelectTriggers(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, CancellationToken)

Selects several triggers at once, chunking the keys into as few statements as the provider's parameter ceiling allows. Keys that have no row are simply absent from the result.

public virtual ValueTask<List<IOperableTrigger>> SelectTriggers(ConnectionAndTransactionHolder conn, IReadOnlyCollection<TriggerKey> triggerKeys, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
triggerKeys IReadOnlyCollection<TriggerKey>: The keys of the triggers to select.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<IOperableTrigger>>

SelectTriggersForCalendar(ConnectionAndTransactionHolder, string, CancellationToken)

Select the triggers for a calendar

public virtual ValueTask<List<IOperableTrigger>> SelectTriggersForCalendar(ConnectionAndTransactionHolder conn, string calendarName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
calendarName string: Name of the calendar.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<IOperableTrigger>>: An array of ITrigger objects associated with a given job.

SelectTriggersForJob(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Select the triggers for a job>

public virtual ValueTask<List<IOperableTrigger>> SelectTriggersForJob(ConnectionAndTransactionHolder conn, JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<IOperableTrigger>>: an array of ITrigger objects associated with a given job.

Remarks

The job's trigger keys, then the whole set in one read. Reading them back one at a time was a round trip per trigger for what SelectTriggers(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, CancellationToken) answers in one (#3424).

SelectTriggersForRecoveringJobs(ConnectionAndTransactionHolder, CancellationToken)

Select all of the triggers for jobs that are requesting recovery. The returned trigger objects will have unique "recoverXXX" trigger names and will be in the DefaultRecoveryGroup trigger group. Each keeps the execution group its firing's trigger carried.

public virtual ValueTask<List<IOperableTrigger>> SelectTriggersForRecoveringJobs(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<IOperableTrigger>>: An array of ITrigger objects

Remarks

In order to preserve the ordering of the triggers, the fire time will be set from the ColumnFiredTime column in the TableFiredTriggers table. The caller is responsible for calling ComputeFirstFireTimeUtc(ICalendar?) on each returned trigger. It is also up to the caller to insert the returned triggers to ensure that they are fired. Each trigger's data map names the firing it replays under FailedJobOriginalTriggerName and the keys beside it; a replay of a recovery trigger keeps the names that trigger's map already carries.

SelectTriggersInState(ConnectionAndTransactionHolder, StoredTriggerState, CancellationToken)

Select all the triggers in a given state.

public virtual ValueTask<List<TriggerKey>> SelectTriggersInState(ConnectionAndTransactionHolder conn, StoredTriggerState state, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
state StoredTriggerState: The state the triggers must be in.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>: An array of trigger TriggerKeys.

SelectTriggersToAcquire(ConnectionAndTransactionHolder, TriggerAcquisitionCriteria, CancellationToken)

Selects the next triggers to fire, in ascending order of fire time and then descending by priority.

public virtual ValueTask<List<TriggerAcquireResult>> SelectTriggersToAcquire(ConnectionAndTransactionHolder conn, TriggerAcquisitionCriteria criteria, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
criteria TriggerAcquisitionCriteria: What to acquire, and how much of it.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerAcquireResult>>: A (never null, possibly empty) list of the next triggers to be fired, refused candidates flagged.

Remarks

A candidate refused for its execution group's limit is best returned with ExecutionGroupAtLimit set rather than left out: the store counts such a row as one it read and skipped, and reads past it to what is due behind it. A delegate that leaves the row out instead still works, but a node reading one trigger at a time cannot then see past a group at its limit (#3928). Every dialect Quartz ships flags the row.

SerializeJobData(JobDataMap)

Remove the transient data from and then create a serialized MemoryStream version of a JobDataMap and returns the underlying bytes.

public virtual byte[]? SerializeJobData(JobDataMap data)

Parameters

data JobDataMap: The data.

Returns

byte[]: the serialized data as byte array

SerializeObject(object?)

Create a serialized byte[] version of an Object.

protected virtual byte[]? SerializeObject(object? obj)

Parameters

obj object: the object to serialize

Returns

byte[]: Serialized object as byte array.

ToSqlEqualsClause<T>(StringMatcher<T>)

The value an exact-match matcher compares with, which needs no escaping because it is bound as a parameter rather than built into the statement.

protected static string ToSqlEqualsClause<T>(StringMatcher<T> matcher) where T : Key<T>

Parameters

matcher StringMatcher<T>: The matcher being translated.

Returns

string

Type Parameters

T

ToSqlLikeClause(StringOperator, string)

Translates a matcher's operator and text into a LIKE pattern.

protected virtual string ToSqlLikeClause(StringOperator compareWith, string compareToValue)

Parameters

compareWith StringOperator
compareToValue string

Returns

string

Remarks

The matcher's own text is a literal, so its wildcard characters are escaped with '!'; the statements this feeds all name that character in an ESCAPE clause. Only the '%' this method adds itself stays a wildcard, so a group literally named "50%" is found by an exact match and by a "starts with 50" one, and not by a "starts with 5" one.

ToSqlLikeClause<T>(StringMatcher<T>)

Translates a group or name matcher into a LIKE pattern.

protected string ToSqlLikeClause<T>(StringMatcher<T> matcher) where T : Key<T>

Parameters

matcher StringMatcher<T>

Returns

string

Type Parameters

T

TriggerExists(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Check whether or not a trigger exists.

public virtual ValueTask<bool> TriggerExists(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: the DB Connection
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>: the number of rows updated

UpdateBlobTrigger(ConnectionAndTransactionHolder, IOperableTrigger, CancellationToken)

Update the blob trigger data.

public virtual ValueTask<int> UpdateBlobTrigger(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: the DB Connection
trigger IOperableTrigger: The trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows updated

UpdateCalendar(ConnectionAndTransactionHolder, string, ICalendar, CancellationToken)

Update a calendar.

public virtual ValueTask<int> UpdateCalendar(ConnectionAndTransactionHolder conn, string calendarName, ICalendar calendar, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
calendarName string: The name for the new calendar.
calendar ICalendar: The calendar.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows updated.

UpdateJobData(ConnectionAndTransactionHolder, IJobDetail, CancellationToken)

Update the job data map for the given job.

public virtual ValueTask<int> UpdateJobData(ConnectionAndTransactionHolder conn, IJobDetail job, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
job IJobDetail: The job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows updated

UpdateJobDetail(ConnectionAndTransactionHolder, IJobDetail, CancellationToken)

Update the job detail record.

public virtual ValueTask<int> UpdateJobDetail(ConnectionAndTransactionHolder conn, IJobDetail job, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
job IJobDetail: The job to update.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: Number of rows updated.

UpdateMisfireOriginalFireTime(ConnectionAndTransactionHolder, TriggerKey, DateTimeOffset?, CancellationToken)

Updates the misfire original fire time for the given trigger.

public virtual ValueTask UpdateMisfireOriginalFireTime(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, DateTimeOffset? fireTime, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder
triggerKey TriggerKey
fireTime DateTimeOffset?
cancellationToken CancellationToken

Returns

ValueTask

UpdateMisfiredTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, DateTimeOffset?, CancellationToken)

Performs a targeted UPDATE of only the columns that change during misfire recovery, bypassing the heavyweight AddTrigger / UpdateTrigger path which performs many unnecessary SELECTs (existence check, pause-group checks, job retrieval, trigger-type lookup) that are redundant for a trigger known to be in WAITING state.

public virtual ValueTask UpdateMisfiredTrigger(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, StoredTriggerState newState, DateTimeOffset? misfireOriginalFireTime, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
trigger IOperableTrigger: The trigger after UpdateAfterMisfire has been applied in-memory.
newState StoredTriggerState: The new trigger state to persist (e.g. WAITING, COMPLETE, BLOCKED).
misfireOriginalFireTime DateTimeOffset?: The original scheduled fire time for "fire now" misfire policies. When non-null, the value is written to the MISFIRE_ORIG_FIRE_TIME column. null leaves the column unchanged, preserving any previously stored original fire time.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

UpdateMisfiredTriggers(ConnectionAndTransactionHolder, IReadOnlyList<MisfiredTriggerUpdate>, CancellationToken)

Applies a whole batch of misfire updates. Semantically identical to calling UpdateMisfiredTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, DateTimeOffset?, CancellationToken) once per entry, but collapses the statements into a single round-trip on providers that support batching.

public virtual ValueTask UpdateMisfiredTriggers(ConnectionAndTransactionHolder conn, IReadOnlyList<MisfiredTriggerUpdate> updates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
updates IReadOnlyList<MisfiredTriggerUpdate>: The triggers, after UpdateAfterMisfire has been applied in-memory.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

UpdateMisfiredTriggersIfUnchanged(ConnectionAndTransactionHolder, IReadOnlyList<MisfiredTriggerUpdate>, CancellationToken)

UpdateMisfiredTriggers(ConnectionAndTransactionHolder, IReadOnlyList<MisfiredTriggerUpdate>, CancellationToken), writing each row only while it still holds the fire time its misfire was decided from (ExpectedNextFireTimeUtc), and saying which rows were written.

public virtual ValueTask<List<TriggerKey>> UpdateMisfiredTriggersIfUnchanged(ConnectionAndTransactionHolder conn, IReadOnlyList<MisfiredTriggerUpdate> updates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
updates IReadOnlyList<MisfiredTriggerUpdate>: The triggers, after UpdateAfterMisfire has been applied in-memory.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>: The keys of the triggers whose row took the write, in the order given.

Remarks

The misfire handler reads under TRIGGER_ACCESS; a firing round of work that allows concurrent execution takes no lock (#4067), so a row exactly a misfire threshold late can be in both their reads, and the round's fire can commit between the handler's read and its write. A write by key would then re-arm the occurrence the round has just fired. Held to the fire time it read, it finds zero rows, and the store neither reports the trigger misfired nor finalized.

A default interface member, so a delegate written against an earlier 4.x keeps compiling; the default calls UpdateMisfiredTriggers(ConnectionAndTransactionHolder, IReadOnlyList<MisfiredTriggerUpdate>, CancellationToken) and answers every key, which is the behaviour such a delegate had. An update whose expectation is null is written as that member writes it, whatever the row holds.

UpdateSchedulerState(ConnectionAndTransactionHolder, string, DateTimeOffset, CancellationToken)

Update a scheduler-instance state record.

public virtual ValueTask<int> UpdateSchedulerState(ConnectionAndTransactionHolder conn, string instanceId, DateTimeOffset checkInTime, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
instanceId string: The instance id.
checkInTime DateTimeOffset: The check in time.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of updated rows.

UpdateTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, IJobDetail, CancellationToken)

Update the base trigger data.

public virtual ValueTask<int> UpdateTrigger(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, StoredTriggerState state, IJobDetail jobDetail, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: the DB Connection
trigger IOperableTrigger: The trigger.
state StoredTriggerState: The state.
jobDetail IJobDetail: The job detail.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows updated

Remarks

In a state that is not paused, StdAdoDelegate also clears the row's PAUSE_REASON, PAUSED_BY and PAUSED_AT in the same statement, so a pause that a replace ended cannot be read back by a later reasonless pause. An override that writes its own statement and leaves them out keeps the behaviour before 4.4.

UpdateTriggerForRetry(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, CancellationToken)

Writes the retry a completing trigger has just scheduled for itself: where it fires next, how many attempts at the current occurrence are behind it, and the state it waits in.

public virtual ValueTask<int> UpdateTriggerForRetry(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, StoredTriggerState newState, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
trigger IOperableTrigger: The completing trigger, carrying the retry instant as its next fire time and the incremented attempt.
newState StoredTriggerState: The state to leave the trigger in — waiting, or paused if its group is.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: How many rows were updated.

Remarks

Narrow on purpose. The trigger's schedule has not changed — only which instant it fires at next — so the generic trigger UPDATE would write a row's worth of columns to move one, and would write back a preferred node and a job data map this path has no business touching.

The completion of a simple trigger that measures its interval from completion writes its next fire time through it too, for the same reason: the instant and the state its hold gives way to, with the attempt the row already holds (#4140).

See Also: RetryTrigger

UpdateTriggerGroupStateFromOtherState(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, StoredTriggerState, StoredTriggerState, CancellationToken)

Update all of the triggers the group matcher selects to the given new state, if they are in the given old state.

public virtual ValueTask<int> UpdateTriggerGroupStateFromOtherState(ConnectionAndTransactionHolder conn, GroupMatcher<TriggerKey> matcher, StoredTriggerState newState, StoredTriggerState oldState, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection
matcher GroupMatcher<TriggerKey>: Criteria for matching groups.
newState StoredTriggerState: The new state for the trigger group
oldState StoredTriggerState: The old state the triggers must be in.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: int the number of rows updated

Remarks

Matcher-based rather than query-based on purpose: this is the pause/resume mutation path, which has to move every matching trigger under one lock and therefore cannot be paged.

UpdateTriggerGroupStateFromOtherStates(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, CancellationToken)

Update all triggers the group matcher selects to the given new state, if they are in one of the given old states.

public virtual ValueTask<int> UpdateTriggerGroupStateFromOtherStates(ConnectionAndTransactionHolder conn, GroupMatcher<TriggerKey> matcher, StoredTriggerState newState, IReadOnlyCollection<StoredTriggerState> oldStates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection
matcher GroupMatcher<TriggerKey>: Criteria for matching groups.
newState StoredTriggerState: The new state for the trigger
oldStates IReadOnlyCollection<StoredTriggerState>: The states a trigger must be in to be updated. Must not be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows updated

Remarks

Matcher-based rather than query-based on purpose: this is the pause/resume mutation path, which has to move every matching trigger under one lock and therefore cannot be paged.

UpdateTriggerIfUnchanged(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, IJobDetail, DateTimeOffset?, CancellationToken)

UpdateTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, IJobDetail, CancellationToken), writing the row only while it still holds the fire time it was read with: an editor's read-modify-write of a trigger that a firing round may move in between.

public virtual ValueTask<int> UpdateTriggerIfUnchanged(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, StoredTriggerState state, IJobDetail jobDetail, DateTimeOffset? expectedNextFireTimeUtc, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
trigger IOperableTrigger: The trigger, as edited.
state StoredTriggerState: The state to store it in.
jobDetail IJobDetail: The job detail.
expectedNextFireTimeUtc DateTimeOffset?: The next fire time the row held when it was read, or null for a row read with none.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows updated: zero when the row moved, or went, since it was read.

Remarks

An editor holding TRIGGER_ACCESS — UpdateTriggerDetails, a calendar update that recomputes its triggers — reads a trigger's row, changes what it was asked to and writes the row back whole. A firing round of work that allows concurrent execution takes no lock (#4067), so it can fire the row between that read and that write; written back by key, the edit would re-arm the occurrence the round has just fired. Held to NEXT_FIRE_TIME as read, the write finds zero rows instead, and the editor reads the row again and applies the edit to it.

A default interface member, so a delegate written against an earlier 4.x keeps compiling; the default is UpdateTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, IJobDetail, CancellationToken) itself, which keeps the behaviour such a delegate had. StdAdoDelegate appends the predicate to the same statement, and writes the trigger's own table only when the row took the write.

UpdateTriggerPreferredNodeConditional(ConnectionAndTransactionHolder, TriggerKey, PreferredNodeTransition, CancellationToken)

Updates the preferred node columns for a trigger only when they still hold the expected values (compare-and-swap). Used by the auto-pin claim/steal in TriggerFired so a concurrent re-pin or clear (e.g. via UpdateTriggerDetails between acquisition and firing) wins over the claim instead of being clobbered by it.

public virtual ValueTask<int> UpdateTriggerPreferredNodeConditional(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, PreferredNodeTransition transition, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
triggerKey TriggerKey: The key identifying the trigger.
transition PreferredNodeTransition: The pin the row must still hold, and the one to put in its place.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: Number of rows updated: 1 when the claim succeeded, 0 when the value changed concurrently.

UpdateTriggerState(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, CancellationToken)

Update the state for a given trigger.

public virtual ValueTask<int> UpdateTriggerState(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, StoredTriggerState state, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
triggerKey TriggerKey: The key identifying the trigger.
state StoredTriggerState: The new state for the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows updated

UpdateTriggerStateFromOtherState(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, StoredTriggerState, CancellationToken)

Update the given trigger to the given new state, if it is in the given old state.

public virtual ValueTask<int> UpdateTriggerStateFromOtherState(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, StoredTriggerState newState, StoredTriggerState oldState, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection
triggerKey TriggerKey: The key identifying the trigger.
newState StoredTriggerState: The new state for the trigger
oldState StoredTriggerState: The old state the trigger must be in
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: int the number of rows updated

UpdateTriggerStateFromOtherStateWithNextFireTime(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, StoredTriggerState, DateTimeOffset, CancellationToken)

Update the given trigger to the given new state, if it is in the given old state and has the given next fire time.

public virtual ValueTask<int> UpdateTriggerStateFromOtherStateWithNextFireTime(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, StoredTriggerState newState, StoredTriggerState oldState, DateTimeOffset nextFireTime, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection
triggerKey TriggerKey: The key identifying the trigger.
newState StoredTriggerState: The new state for the trigger
oldState StoredTriggerState: The old state the trigger must be in
nextFireTime DateTimeOffset: The next fire time the trigger must have
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: int the number of rows updated

Remarks

Virtual like every other statement-issuing member on this class, and worth saying why on this one: it is the lock-free acquisition path's claim on a trigger, so it is the statement a dialect is most likely to need to reshape — an index hint, a different way of spelling the conditional update. It was the one IDriverDelegate member StdAdoDelegate implemented non-virtually, which was an oversight rather than a decision; the value conversions that are deliberately not virtual say so on themselves.

UpdateTriggerStateFromOtherStates(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, CancellationToken)

Update the given trigger to the given new state, if it is one of the given old states.

public virtual ValueTask<int> UpdateTriggerStateFromOtherStates(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, StoredTriggerState newState, IReadOnlyCollection<StoredTriggerState> oldStates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection
triggerKey TriggerKey: The key identifying the trigger.
newState StoredTriggerState: The new state for the trigger
oldStates IReadOnlyCollection<StoredTriggerState>: The states the trigger must be in to be updated. Must not be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: int the number of rows updated

UpdateTriggerStatesForJob(ConnectionAndTransactionHolder, JobKey, StoredTriggerState, CancellationToken)

Update the states of all triggers associated with the given job, leaving any trigger in Awaiting as it is.

public virtual ValueTask<int> UpdateTriggerStatesForJob(ConnectionAndTransactionHolder conn, JobKey jobKey, StoredTriggerState state, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
state StoredTriggerState: The new state for the triggers.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows updated

Remarks

The statement behind SetAllJobTriggersError and SetAllJobTriggersComplete, both issued by a completion of one of the job's triggers. An awaiting trigger belongs to its parent's settlement rather than to that firing, and moved to another state it would be waiting for its parent in a state the parent's completion cannot release it from.

UpdateTriggerStatesForJobFromOtherState(ConnectionAndTransactionHolder, JobKey, StoredTriggerState, StoredTriggerState, CancellationToken)

Update the states of any triggers associated with the given job, that are the given current state.

public virtual ValueTask<int> UpdateTriggerStatesForJobFromOtherState(ConnectionAndTransactionHolder conn, JobKey jobKey, StoredTriggerState newState, StoredTriggerState oldState, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
newState StoredTriggerState: The new state for the triggers
oldState StoredTriggerState: The old state of the triggers
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows updated

UpdateTriggerStatesForJobFromOtherState(ConnectionAndTransactionHolder, JobKey, IReadOnlyList<TriggerStateTransition>, CancellationToken)

Apply several conditional state changes to a job's triggers in as few round trips as the provider allows.

public virtual ValueTask UpdateTriggerStatesForJobFromOtherState(ConnectionAndTransactionHolder conn, JobKey jobKey, IReadOnlyList<TriggerStateTransition> transitions, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
transitions IReadOnlyList<TriggerStateTransition>: The state changes to apply, in order.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

The transitions are applied in the order given, so a set of them that overlaps means what issuing them one after another meant. Blocking and unblocking a job's triggers is always two or three of these at once, which is two or three round trips inside the trigger-access lock when they travel separately.

UpdateTriggerStatesForJobsFromOtherState(ConnectionAndTransactionHolder, IReadOnlyCollection<JobKey>, StoredTriggerState, StoredTriggerState, CancellationToken)

Apply the same conditional state change to the triggers of each of several jobs, in as few round trips as the provider allows.

public virtual ValueTask UpdateTriggerStatesForJobsFromOtherState(ConnectionAndTransactionHolder conn, IReadOnlyCollection<JobKey> jobKeys, StoredTriggerState newState, StoredTriggerState oldState, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKeys IReadOnlyCollection<JobKey>: The keys identifying the jobs. An empty collection does nothing.
newState StoredTriggerState: The new state for the triggers
oldState StoredTriggerState: The old state a trigger must be in to be updated
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

The same statement as the single-job overload, once per job key, issued as one DbBatch where the provider supports batching. Cluster recovery unblocks the siblings of every interrupted execution, which is one or two of these per fired-trigger row when they travel separately — and the same job over and over when a dead node left several rows behind. No row count comes back: a batch does not report one per command in any portable way, and the caller counts the rows it asked about rather than the rows that moved.

UpdateTriggerStatesFromOtherStateWithNextFireTime(ConnectionAndTransactionHolder, IReadOnlyList<TriggerClaim>, StoredTriggerState, StoredTriggerState, CancellationToken)

Update each of the given triggers to the given new state, if it is in the given old state and still has the next fire time it is claimed with.

public virtual ValueTask<List<TriggerKey>> UpdateTriggerStatesFromOtherStateWithNextFireTime(ConnectionAndTransactionHolder conn, IReadOnlyList<TriggerClaim> claims, StoredTriggerState newState, StoredTriggerState oldState, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
claims IReadOnlyList<TriggerClaim>: The triggers to claim, each with the next fire time it was read with.
newState StoredTriggerState: The new state for the triggers.
oldState StoredTriggerState: The old state each trigger must be in.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>: The keys of the triggers whose row moved, in the order given. A claim that found its row in another state, or due at another time, is absent.

Remarks

The plural of UpdateTriggerStateFromOtherStateWithNextFireTime(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, StoredTriggerState, DateTimeOffset, CancellationToken), for an acquisition that fires what is due in the same transaction (#3864): its claims go together, where the provider can batch them. StdAdoDelegate sends them as one DbBatch. Called only for a delegate that answers SupportsFireOnAcquire with true.

A default interface member, so a delegate written against an earlier 4.x keeps working: the default is the single-trigger call for each claim, in order.

UpdateTriggerStatesFromOtherStates(ConnectionAndTransactionHolder, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, CancellationToken)

Update all triggers having one of the given states, to the given new state.

public virtual ValueTask<int> UpdateTriggerStatesFromOtherStates(ConnectionAndTransactionHolder conn, StoredTriggerState newState, IReadOnlyCollection<StoredTriggerState> oldStates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
newState StoredTriggerState: The new state for the triggers
oldStates IReadOnlyCollection<StoredTriggerState>: The states a trigger must be in to be updated. Must not be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: Number of rows updated

UpdateTriggerStatesFromOtherStates(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, CancellationToken)

Moves a whole set of triggers to the given new state, each one only if it is in one of the given old states.

public virtual ValueTask<int> UpdateTriggerStatesFromOtherStates(ConnectionAndTransactionHolder conn, IReadOnlyCollection<TriggerKey> triggerKeys, StoredTriggerState newState, IReadOnlyCollection<StoredTriggerState> oldStates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection
triggerKeys IReadOnlyCollection<TriggerKey>: The keys identifying the triggers. May be empty.
newState StoredTriggerState: The new state for the triggers
oldStates IReadOnlyCollection<StoredTriggerState>: The states a trigger must be in to be updated. Must not be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows updated.

Remarks

The key-set form of the member above, for the paths that decide one transition for a set of keys and then have no reason to issue it a key at a time: pause, resume, and cluster recovery releasing every trigger a dead node had reserved. A set of one old state is how a caller that wants exactly one asks for it.

The default implementation is the per-key loop, so a delegate that says nothing about key sets keeps behaving as it did. StdAdoDelegate issues one UPDATE with a key-set predicate per chunk, so the row count is the database's own and not a tally of what was asked about.

ValidateSchema(ConnectionAndTransactionHolder, CancellationToken)

Verifies that the schema objects this delegate reads and writes are there, and reports how many were checked.

public virtual ValueTask<int> ValidateSchema(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of schema objects validated.

Remarks

Called at startup for every SchemaProvisioning but None, so that a missing or mis-prefixed table is reported once, by name, instead of as the first failing operation. A delegate that owns tables of its own checks those too.

Tables, and the columns 4.x added to the tables 3.x already had: a schema that took none of the 4.0 migration is missing one table and six columns, and a table-level check alone would pass a database that then fails every acquisition for ever. What it does not check is the shape of a column — a type or a width that a hand-built table got wrong is still found by the statement that binds it.

Exceptions

JobPersistenceException: An object could not be queried.

Table of Contents

Class StdAdoDelegate

Remarks

Properties

AdditionalLikeWildcards

Property Value

Remarks

CanUseProperties

Property Value

Remarks

DbProvider

Property Value

FiltersAcquisitionExecutionGroups

Property Value

Remarks

FiltersAcquisitionJobTypeExclusions

Property Value

Remarks

SchedulerName

Property Value

Remarks

SchemaResourceName

Property Value

Remarks

SupportsFireOnAcquire

Property Value

Remarks

Methods

AddCommandParameter(DbCommand, string, object?, Enum?, int?)

Parameters

AddDefaultTriggerPersistenceDelegates()

Remarks

AddExecutionGroupParameters(DbCommand, ExecutionGroupClauseShape, IReadOnlyCollection<ExecutionGroupScope>?)

Parameters

AddPagingParameters(DbCommand, int, int, bool)

Parameters

AddPreferredNodeParameters(DbCommand, DateTimeOffset)

Parameters

AddTriggerPersistenceDelegate(ITriggerPersistenceDelegate)

Parameters

Remarks

ApplyPaging(string, bool)

Parameters

Returns

Remarks

ApplyTriggerFired(ConnectionAndTransactionHolder, TriggerFiredUpdate, CancellationToken)

Parameters

Returns

Remarks

ApplyTriggersFired(ConnectionAndTransactionHolder, IReadOnlyList<TriggerFiredUpdate>, CancellationToken)

Parameters

Returns

Remarks

CalendarExists(ConnectionAndTransactionHolder, string, CancellationToken)

Parameters

Returns

CalendarIsReferenced(ConnectionAndTransactionHolder, string, CancellationToken)

Parameters

Returns

ClearData(ConnectionAndTransactionHolder, CancellationToken)

Parameters

Returns

Remarks

ClearMisfireOriginalFireTime(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Parameters

Returns

Remarks

ClearTriggerPauses(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, CancellationToken)

Parameters

Returns

Remarks

ClearTriggerRetryAttempt(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Parameters

Returns

Remarks

ConvertFromProperty(NameValueCollection)

Parameters

Returns

ConvertToProperty(IDictionary<string, object?>)

Parameters