null - AsynchronousV1

AsynchronousV1

global with sharing virtual class AsynchronousV1

Description	Copyright (c) 2025 Mark Brennand, released under MIT License. Class defining the services offered by the Asynchronous API. All access to the API must be through this class. Asynchronous jobs should first be created using the createJob method. They can then be run by calling the queueJobs method. See README for full details of the Asynchronous API.
Author	Mark Brennand

Properties

Status	global enum Status Defines the status of an AsynchronousJob__c object under the control of this framework. A job can only be in a single state at any one time. PENDING - The job has been created but a job has not been queued for it. QUEUED - The job has been queued for processing. RUNNING - The job is running. SUCCEEDED - The job ran to completion successfully. FAILED - The last job failed to run and the maximum number of retries has been exceeded. CANCELLED - The job has been cancelled.

Status

global enum Status

Defines the status of an AsynchronousJob__c object under the control of this framework.

A job can only be in a single state at any one time.

PENDING - The job has been created but a job has not been queued for it.

QUEUED - The job has been queued for processing.

RUNNING - The job is running.

SUCCEEDED - The job ran to completion successfully.

FAILED - The last job failed to run and the maximum number of retries has been exceeded.

CANCELLED - The job has been cancelled.

Methods

createJob

global static Job createJob( final Type type, final String reference, final Integer maximumRetries, final Integer retryInterval, final Map<String, String> state )

Description	Creates a new instance of a job to be managed by the injected API implementation. The Apex class must implement the Runnable interface. If it doesn't, the implementation will throw an exception. The state is data specific to the job. It is passed to the Runnable for the job when it is invoked. It can contain any data an application chooses. For example, it may include arguments specific to the job.
Parameter	type: The Apex class of the job to be run.
Parameter	reference: The user's reference for the job.
Parameter	maximumRetries: The maximum number of retries to make before failing the job.
Parameter	retryInterval: The number of milliseconds between each re-try event.
Parameter	state: Job specific data.
Returns	The job.

queueJobs

global static List<Job> queueJobs(final List<Job> asyncJobs)

Description	Schedules the given job for processing by the injected API implementation.
Parameter	asyncJobs: The jobs to schedule for processing.
Returns	The jobs queued for processing.

AsynchronousV1.APIException

global with sharing class APIException extends Exception

Description	Exception thrown when an operation in the Asynchronous API fails.

AsynchronousV1.Job

global interface Job

Description	Information about a job being managed by the framework. The implementation will be specific to the API implementation.

Methods

getLastRunTime

Datetime getLastRunTime()

Description	Returns the date and time at which the API implementation last run the job.
Returns	The date and time.

getMaximumRetries

Integer getMaximumRetries()

Description	Returns the maximum number of re-tries to be made to process the job by the API implementation if it fails to run. Each re-try will be made if the Runnable.run method throws an Exception.
Returns	The maximum number.

getOwnerId

String getOwnerId()

Description	Returns the id of the user the job is being run for by the API implementation.
Returns	The user id.

getReference

String getReference()

Description	Returns the user's reference assigned to the job on creation by the API implementation.
Returns	The reference.

getRetriesRemaining

Integer getRetriesRemaining()

Description	Returns the number of re-tries that are remaining to be made by the API implementation for the job.
Returns	Number of re-tries remaining.

getRetryInterval

Integer getRetryInterval()

Description	Returns the number of milliseconds that the implementation of the API will wait between re-try attempts.
Returns	The number of milliseconds.

getRetryNumber

Integer getRetryNumber()

Description	The current number of re-tries made by the API implementation for the job. Re-try number 0 is the first attempt to run it.
Returns	The current re-try number.

getRunnable

RunnableJob getRunnable()

Description	Returns the Runnable implementation for ths job managed by the API implementation.
Returns	The Runnable implementation.

getScheduledRunTime

Datetime getScheduledRunTime()

Description	Returns the date and time at which the API implementation is next scheduled to run the job.
Returns	The date and time.

getState

Map<String, String> getState()

Description	Returns the state information assigned to the job on creation by the API implementation. The state may be updated by the call to Runnable.run for the job, though only when no Exception is thrown by the method.
Returns	The job's state.

getStatus

Status getStatus()

Description	Return the current status of the job managed by the API implementation.
Returns	The jobs's status.

setState

void setState(Map<String, String> state)

Description	Sets a new state for the job managed by the API implementation New state will only be preserved if the Apex request it is set within does not throw an Exception.
Parameter	state: The new state.

AsynchronousV1.RunnableJob

global interface RunnableJob

Description	Interface defining the logic specific to a job run by the framework. When the job is run by the framework, the job specific implementation of this interface is created and its run method is called. As a new Runnable instance is created each time the job is run, implementations of this interface cannot preserve state in member variables. The Job's state can be used for that. Concurrency is controlled by the maximum active value. Any implementation of the API must guarantee that no more than this number of instances of the Runnable may be active at any one time. The AsynchronousRunnable class provides a full implementation of this interface. If possible you should use this class and only override the methods you need behaviour other than the default for.

Description

Interface defining the logic specific to a job run by the framework.

When the job is run by the framework, the job specific implementation of this interface is created and its run method is called. As a new Runnable instance is created each time the job is run, implementations of this interface cannot preserve state in member variables. The Job's state can be used for that.

Concurrency is controlled by the maximum active value. Any implementation of the API must guarantee that no more than this number of instances of the Runnable may be active at any one time.

The AsynchronousRunnable class provides a full implementation of this interface. If possible you should use this class and only override the methods you need behaviour other than the default for.

Methods

getMaximumActive

Integer getMaximumActive()

Description	Concurrency is controlled by the RunnableJob's implementation. The maximum active value defines how many instances of the RunnableJob's implementation may be active concurrently. Any implementation of the API interface must guarantee that this value is enforced.
Returns	The maximum number of active instances.

getType

Type getType()

Description	The class of the RunnableJob's implementation. The class can either be a Runnable or Types.Factory implementation. In the case of the latter, the class returned by the newInstance method must implement Runnable.
Returns	The Apex class of the RunnableJob implementation.

onCancellation

Boolean onCancellation(Job asyncJob)

Description	Called when a job has been cancelled. The return value indicates whether the API implementation is to keep a record of the job or delete it.
Parameter	asyncJob: The job that has been cancelled.
Returns	Whether to delete a record of the job or not.

onError

Status onError(Job asyncJob, Exception exc)

Description	An API implementation must call this method each time an Exception is caught when running a job. The Exception will be thrown from the RunnableJob.run method. A Status of QUEUED should be returned in most circumstances to re-try the job. Say, for example though, that a particular type of Exception was thrown that meant the job would always fail, a Status of CANCELLED could be returned to indicate no further re-tries are to be performed. The return value indicates new Status value to assign to the job.
Parameter	asyncJob: The job that has been cancelled.
Parameter	exc: The exception caught by the framework whilst running the job.
Returns	The new Status of the job.

onFailure

Boolean onFailure(Job asyncJob, Exception exc)

Description	Called when a job has failed to run and all is re-tries have been exhausted. The return value indicates whether the API implementation is to keep a record of the job or delete it.
Parameter	asyncJob: The job that failed.
Parameter	exc: The Exception that caused the job to fail on its last execution.
Returns	Whether to delete a record of the job or not.

onSuccess

Boolean onSuccess(Job asyncJob)

Description	Called when a job has run to completion successfully in the framework. The return value indicates whether the API implementation is to keep a record of the job or delete it.
Parameter	asyncJob: The job that ran to completion.
Returns	Whether to delete a record of the job or not.

run

void run(Job asyncJob, String apexJobId)

Description	Called when the job is run by the framework. Any job specific data set in the state when the job was created can be accessed from the state in the job argument.
Parameter	asyncJob: The job being run.
Parameter	apexJobId: The Id of the Apex job for the RunnableJob.

AsynchronousV1.Runnable

global with sharing abstract class Runnable extends AsynchronousAPI.ApexJobRunnable

Description	Implementation of RunnableJob that classes may extend to make coding the logic of a job simpler. Default implementations of all the methods are coded in this class. They may be overridden. The Asynchronous.ApexJobRunnable.run() method will need to be implemented to code the logic for the job. Classes extending this class must have a no-op constructor which calls the constructor for this class with the Type of the extending class.

Description

Implementation of RunnableJob that classes may extend to make coding the logic of a job simpler.

Default implementations of all the methods are coded in this class. They may be overridden.

The Asynchronous.ApexJobRunnable.run() method will need to be implemented to code the logic for the job.

Classes extending this class must have a no-op constructor which calls the constructor for this class with the Type of the extending class.

Methods

getMaximumActive

global virtual Integer getMaximumActive()

Description	Returns the maximum number of concurrent executions of the Runnable that are allowed. If the concurrency is exceeded, a job will not be started.
Returns	Maximum concurrent executions.

onCancellation

global virtual Boolean onCancellation(final Job asyncJob)

Description	Called when an Asynchronous__c object has its status changed to CANCELLED.
Parameter	asyncJob: The job that has been cancelled.
Returns	True if the Asynchronous__c object is to be kept, false if not.

onError

global virtual Status onError(final Job asyncJob, final Exception exc)

Description	Called when an Exception occurs during the running of an Asynchronous__c object and there are re-tries left to be made. The status value returned by this method determines what happens to the job. Return QUEUED to re-try the job. Return CANCELLED if the job is not to be re-tried and no further processing of it is to be made. The onCancellation method of this class will be called.
Parameter	asyncJob: The job the Exception was thrown for.
Parameter	exc: The Exception that was thrown.
Returns	The new status for the job.

onFailure

global virtual Boolean onFailure(final Job asyncJob, final Exception exc)

Description	Called on failure to run the job after exhausting the Asynchronous__c object's re-tries. To fail, the class's run method must have thrown an Exception every time it was called.
Parameter	asyncJob: The job that has failed.
Parameter	exc: The Exception that caused the last re-try for the job to fail.
Returns	True if the Asynchronous__c object is to be kept, false if not.

onSuccess

global virtual Boolean onSuccess(final Job asyncJob)

Description	Called on successful completion of the Asynchronous__c object for the class. To succeed, the class's run method must not have thrown an Exception when called.
Parameter	asyncJob: The job that has succeeded.
Returns	True if the Asynchronous__c object is to be kept, false if not.

Runnable

global Runnable(final Type type)

Description	Constructs an instance of the class which is a proxy for the sub-class to be run.
Parameter	type: The sub-class to be run.

Force-Framework

AsynchronousV1

Methods

AsynchronousV1.APIException

AsynchronousV1.Job

Methods

AsynchronousV1.RunnableJob

Methods

AsynchronousV1.Runnable

Methods