Nextcloud PHP API (master)

IJobList
in

Interface IJobList

This interface provides functions to register background jobs

To create a new background job create a new class that inherits from either \OCP\BackgroundJob\Job, \OCP\BackgroundJob\QueuedJob or \OCP\BackgroundJob\TimedJob and register it using ->add($job, $argument), $argument will be passed to the run() function of the job when the job is executed.

A regular job will be executed every time cron.php is run, a QueuedJob will only run once and a TimedJob will only run at a specific interval which is to be specified in the constructor of the job by calling $this->setInterval($interval) with $interval in seconds.

This interface should be used directly and not implemented by an application. The implementation is provided by the server.

Tags
since
7.0.0

Table of Contents

Methods

add()  : void
Add a job to the list
countByClass()  : array<int, array{class: class-string, count: int}>
Returns a count of jobs per Job class
getById()  : IJob|null
getDetailsById()  : array<string|int, mixed>|null
getJobs()  : array<string|int, IJob>
Get jobs matching the search
getJobsIterator()  : iterable<string|int, IJob>
Get jobs matching the search
getNext()  : IJob|null
Get the next job in the list
has()  : bool
check if a job is in the list
hasReservedJob()  : bool
Checks whether a job of the passed class was reserved to run in the last 6h
remove()  : void
Remove a job from the list
removeById()  : void
Remove a job from the list by id
resetBackgroundJob()  : void
Reset the $job so it executes on the next trigger
scheduleAfter()  : void
Add a job to the list but only run it after the given timestamp
setExecutionTime()  : void
set the run duration of $job
setLastJob()  : void
set the job that was last ran to the current time
setLastRun()  : void
set the lastRun of $job to now
unlockJob()  : void
Remove the reservation for a job

Methods

add()

Add a job to the list

public add(IJob|IJob> $job[, mixed $argument = null ]) : void
Parameters
$job : IJob|IJob>
$argument : mixed = null

The argument to be passed to $job->run() when the job is executed

Tags
since
7.0.0

countByClass()

Returns a count of jobs per Job class

public countByClass() : array<int, array{class: class-string, count: int}>
Tags
since
30.0.0
Return values
array<int, array{class: class-string, count: int}>

getById()

public getById(int $id) : IJob|null
Parameters
$id : int
Tags
since
7.0.0
Return values
IJob|null

getDetailsById()

public getDetailsById(int $id) : array<string|int, mixed>|null
Parameters
$id : int
Tags
since
23.0.0
Return values
array<string|int, mixed>|null

getJobs()

Get jobs matching the search

public getJobs(IJob|IJob>|null $job, int|null $limit, int $offset) : array<string|int, IJob>

Use getJobsIterator instead to avoid duplicated job objects

Parameters
$job : IJob|IJob>|null
$limit : int|null
$offset : int
Tags
since
25.0.0
Return values
array<string|int, IJob>

getJobsIterator()

Get jobs matching the search

public getJobsIterator(IJob|IJob>|null $job, int|null $limit, int $offset) : iterable<string|int, IJob>
Parameters
$job : IJob|IJob>|null
$limit : int|null
$offset : int
Tags
since
26.0.0
Return values
iterable<string|int, IJob>

getNext()

Get the next job in the list

public getNext([bool $onlyTimeSensitive = false ][, array<string|int, IJob>>|null $jobClasses = null ]) : IJob|null
Parameters
$onlyTimeSensitive : bool = false

Whether we get only time sensitive jobs or not

$jobClasses : array<string|int, IJob>>|null = null

List of job classes to restrict which next job we get

Tags
since
7.0.0
  • In 24.0.0 parameter $onlyTimeSensitive got added; In 30.0.0 parameter $jobClasses got added
Return values
IJob|null —

the next job to run. Beware that this object may be a singleton and may be modified by the next call to buildJob.

has()

check if a job is in the list

public has(IJob|IJob> $job, mixed $argument) : bool
Parameters
$job : IJob|IJob>
$argument : mixed
Tags
since
7.0.0
Return values
bool

hasReservedJob()

Checks whether a job of the passed class was reserved to run in the last 6h

public hasReservedJob(string|null $className) : bool
Parameters
$className : string|null
Tags
since
27.0.0
Return values
bool

remove()

Remove a job from the list

public remove(IJob|IJob> $job[, mixed $argument = null ]) : void
Parameters
$job : IJob|IJob>
$argument : mixed = null
Tags
since
7.0.0

removeById()

Remove a job from the list by id

public removeById(int $id) : void
Parameters
$id : int
Tags
since
30.0.0

resetBackgroundJob()

Reset the $job so it executes on the next trigger

public resetBackgroundJob(IJob $job) : void
Parameters
$job : IJob
Tags
since
23.0.0

scheduleAfter()

Add a job to the list but only run it after the given timestamp

public scheduleAfter(IJob> $job, int $runAfter[, mixed $argument = null ]) : void

For cron background jobs this means the job will likely run shortly after the timestamp has been reached. For ajax background jobs the job might only run when users are active on the instance again.

Parameters
$job : IJob>
$runAfter : int
$argument : mixed = null

The serializable argument to be passed to $job->run() when the job is executed

Tags
since
28.0.0

setExecutionTime()

set the run duration of $job

public setExecutionTime(IJob $job, int $timeTaken) : void
Parameters
$job : IJob
$timeTaken : int
Tags
since
12.0.0

setLastJob()

set the job that was last ran to the current time

public setLastJob(IJob $job) : void
Parameters
$job : IJob
Tags
since
7.0.0

setLastRun()

set the lastRun of $job to now

public setLastRun(IJob $job) : void
Parameters
$job : IJob
Tags
since
7.0.0

unlockJob()

Remove the reservation for a job

public unlockJob(IJob $job) : void
Parameters
$job : IJob
Tags
since
9.1.0 

        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results