IJobList.php 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157
  1. <?php
  2. /**
  3. * @copyright Copyright (c) 2016, ownCloud, Inc.
  4. *
  5. * @author Joas Schilling <coding@schilljs.com>
  6. * @author Morris Jobke <hey@morrisjobke.de>
  7. * @author Noveen Sachdeva <noveen.sachdeva@research.iiit.ac.in>
  8. * @author Robin Appelman <robin@icewind.nl>
  9. * @author Robin McCorkell <robin@mccorkell.me.uk>
  10. * @author Côme Chilliet <come.chilliet@nextcloud.com>
  11. *
  12. * @license AGPL-3.0
  13. *
  14. * This code is free software: you can redistribute it and/or modify
  15. * it under the terms of the GNU Affero General Public License, version 3,
  16. * as published by the Free Software Foundation.
  17. *
  18. * This program is distributed in the hope that it will be useful,
  19. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  21. * GNU Affero General Public License for more details.
  22. *
  23. * You should have received a copy of the GNU Affero General Public License, version 3,
  24. * along with this program. If not, see <http://www.gnu.org/licenses/>
  25. *
  26. */
  27. namespace OCP\BackgroundJob;
  28. /**
  29. * Interface IJobList
  30. *
  31. * This interface provides functions to register background jobs
  32. *
  33. * To create a new background job create a new class that inherits from either
  34. * \OC\BackgroundJob\Job, \OC\BackgroundJob\QueuedJob or
  35. * \OC\BackgroundJob\TimedJob and register it using ->add($job, $argument),
  36. * $argument will be passed to the run() function of the job when the job is
  37. * executed.
  38. *
  39. * A regular job will be executed every time cron.php is run, a QueuedJob will
  40. * only run once and a TimedJob will only run at a specific interval which is to
  41. * be specified in the constructor of the job by calling
  42. * $this->setInterval($interval) with $interval in seconds.
  43. *
  44. * This interface should be used directly and not implemented by an application.
  45. * The implementation is provided by the server.
  46. *
  47. * @since 7.0.0
  48. */
  49. interface IJobList {
  50. /**
  51. * Add a job to the list
  52. *
  53. * @param IJob|class-string<IJob> $job
  54. * @param mixed $argument The argument to be passed to $job->run() when the job is executed
  55. * @since 7.0.0
  56. */
  57. public function add($job, $argument = null): void;
  58. /**
  59. * Remove a job from the list
  60. *
  61. * @param IJob|class-string<IJob> $job
  62. * @param mixed $argument
  63. * @since 7.0.0
  64. */
  65. public function remove($job, $argument = null): void;
  66. /**
  67. * check if a job is in the list
  68. *
  69. * @param IJob|class-string<IJob> $job
  70. * @param mixed $argument
  71. * @since 7.0.0
  72. */
  73. public function has($job, $argument): bool;
  74. /**
  75. * Get jobs matching the search
  76. *
  77. * @param IJob|class-string<IJob>|null $job
  78. * @return array<IJob>
  79. * @since 25.0.0
  80. * @deprecated 26.0.0 Use getJobsIterator instead to avoid duplicated job objects
  81. */
  82. public function getJobs($job, ?int $limit, int $offset): array;
  83. /**
  84. * Get jobs matching the search
  85. *
  86. * @param IJob|class-string<IJob>|null $job
  87. * @return iterable<IJob>
  88. * @since 26.0.0
  89. */
  90. public function getJobsIterator($job, ?int $limit, int $offset): iterable;
  91. /**
  92. * get the next job in the list
  93. *
  94. * @since 7.0.0 - In 24.0.0 parameter $onlyTimeSensitive got added
  95. */
  96. public function getNext(bool $onlyTimeSensitive = false): ?IJob;
  97. /**
  98. * @since 7.0.0
  99. */
  100. public function getById(int $id): ?IJob;
  101. /**
  102. * @since 23.0.0
  103. */
  104. public function getDetailsById(int $id): ?array;
  105. /**
  106. * set the job that was last ran to the current time
  107. *
  108. * @since 7.0.0
  109. */
  110. public function setLastJob(IJob $job): void;
  111. /**
  112. * Remove the reservation for a job
  113. *
  114. * @since 9.1.0
  115. */
  116. public function unlockJob(IJob $job): void;
  117. /**
  118. * set the lastRun of $job to now
  119. *
  120. * @since 7.0.0
  121. */
  122. public function setLastRun(IJob $job): void;
  123. /**
  124. * set the run duration of $job
  125. *
  126. * @since 12.0.0
  127. */
  128. public function setExecutionTime(IJob $job, int $timeTaken): void;
  129. /**
  130. * Reset the $job so it executes on the next trigger
  131. *
  132. * @since 23.0.0
  133. */
  134. public function resetBackgroundJob(IJob $job): void;
  135. /**
  136. * Checks whether a job of the passed class is reserved to run
  137. *
  138. * @param string|null $className
  139. * @return bool
  140. * @since 27.0.0
  141. */
  142. public function hasReservedJob(?string $className): bool;
  143. }