1
0

Task.php 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
  5. * SPDX-License-Identifier: AGPL-3.0-or-later
  6. */
  7. namespace OCP\TaskProcessing;
  8. use DateTime;
  9. use OCP\TaskProcessing\Exception\ValidationException;
  10. /**
  11. * This is a task processing task
  12. *
  13. * @since 30.0.0
  14. */
  15. final class Task implements \JsonSerializable {
  16. protected ?int $id = null;
  17. protected ?DateTime $completionExpectedAt = null;
  18. protected ?array $output = null;
  19. protected ?string $errorMessage = null;
  20. protected ?float $progress = null;
  21. protected int $lastUpdated;
  22. /**
  23. * @since 30.0.0
  24. */
  25. public const STATUS_CANCELLED = 5;
  26. /**
  27. * @since 30.0.0
  28. */
  29. public const STATUS_FAILED = 4;
  30. /**
  31. * @since 30.0.0
  32. */
  33. public const STATUS_SUCCESSFUL = 3;
  34. /**
  35. * @since 30.0.0
  36. */
  37. public const STATUS_RUNNING = 2;
  38. /**
  39. * @since 30.0.0
  40. */
  41. public const STATUS_SCHEDULED = 1;
  42. /**
  43. * @since 30.0.0
  44. */
  45. public const STATUS_UNKNOWN = 0;
  46. /**
  47. * @psalm-var self::STATUS_*
  48. */
  49. protected int $status = self::STATUS_UNKNOWN;
  50. /**
  51. * @param string $taskTypeId
  52. * @param array<string,list<numeric|string>|numeric|string> $input
  53. * @param string $appId
  54. * @param string|null $userId
  55. * @param null|string $customId An arbitrary customId for this task. max length: 255 chars
  56. * @since 30.0.0
  57. */
  58. final public function __construct(
  59. protected readonly string $taskTypeId,
  60. protected array $input,
  61. protected readonly string $appId,
  62. protected readonly ?string $userId,
  63. protected readonly ?string $customId = '',
  64. ) {
  65. $this->lastUpdated = time();
  66. }
  67. /**
  68. * @since 30.0.0
  69. */
  70. final public function getTaskTypeId(): string {
  71. return $this->taskTypeId;
  72. }
  73. /**
  74. * @psalm-return self::STATUS_*
  75. * @since 30.0.0
  76. */
  77. final public function getStatus(): int {
  78. return $this->status;
  79. }
  80. /**
  81. * @psalm-param self::STATUS_* $status
  82. * @since 30.0.0
  83. */
  84. final public function setStatus(int $status): void {
  85. $this->status = $status;
  86. }
  87. /**
  88. * @param ?DateTime $at
  89. * @since 30.0.0
  90. */
  91. final public function setCompletionExpectedAt(?DateTime $at): void {
  92. $this->completionExpectedAt = $at;
  93. }
  94. /**
  95. * @return ?DateTime
  96. * @since 30.0.0
  97. */
  98. final public function getCompletionExpectedAt(): ?DateTime {
  99. return $this->completionExpectedAt;
  100. }
  101. /**
  102. * @return int|null
  103. * @since 30.0.0
  104. */
  105. final public function getId(): ?int {
  106. return $this->id;
  107. }
  108. /**
  109. * @param int|null $id
  110. * @since 30.0.0
  111. */
  112. final public function setId(?int $id): void {
  113. $this->id = $id;
  114. }
  115. /**
  116. * @param null|array<array-key, list<numeric|string>|numeric|string> $output
  117. * @since 30.0.0
  118. */
  119. final public function setOutput(?array $output): void {
  120. $this->output = $output;
  121. }
  122. /**
  123. * @return array<array-key, list<numeric|string>|numeric|string>|null
  124. * @since 30.0.0
  125. */
  126. final public function getOutput(): ?array {
  127. return $this->output;
  128. }
  129. /**
  130. * @return array<array-key, list<numeric|string>|numeric|string>
  131. * @since 30.0.0
  132. */
  133. final public function getInput(): array {
  134. return $this->input;
  135. }
  136. /**
  137. * @return string
  138. * @since 30.0.0
  139. */
  140. final public function getAppId(): string {
  141. return $this->appId;
  142. }
  143. /**
  144. * @return null|string
  145. * @since 30.0.0
  146. */
  147. final public function getCustomId(): ?string {
  148. return $this->customId;
  149. }
  150. /**
  151. * @return string|null
  152. * @since 30.0.0
  153. */
  154. final public function getUserId(): ?string {
  155. return $this->userId;
  156. }
  157. /**
  158. * @return int
  159. * @since 30.0.0
  160. */
  161. final public function getLastUpdated(): int {
  162. return $this->lastUpdated;
  163. }
  164. /**
  165. * @param int $lastUpdated
  166. * @since 30.0.0
  167. */
  168. final public function setLastUpdated(int $lastUpdated): void {
  169. $this->lastUpdated = $lastUpdated;
  170. }
  171. /**
  172. * @psalm-return array{id: ?int, lastUpdated: int, type: string, status: 'STATUS_CANCELLED'|'STATUS_FAILED'|'STATUS_SUCCESSFUL'|'STATUS_RUNNING'|'STATUS_SCHEDULED'|'STATUS_UNKNOWN', userId: ?string, appId: string, input: array<array-key, list<numeric|string>|numeric|string>, output: ?array<array-key, list<numeric|string>|numeric|string>, customId: ?string, completionExpectedAt: ?int, progress: ?float}
  173. * @since 30.0.0
  174. */
  175. final public function jsonSerialize(): array {
  176. return [
  177. 'id' => $this->getId(),
  178. 'type' => $this->getTaskTypeId(),
  179. 'lastUpdated' => $this->getLastUpdated(),
  180. 'status' => self::statusToString($this->getStatus()),
  181. 'userId' => $this->getUserId(),
  182. 'appId' => $this->getAppId(),
  183. 'input' => $this->getInput(),
  184. 'output' => $this->getOutput(),
  185. 'customId' => $this->getCustomId(),
  186. 'completionExpectedAt' => $this->getCompletionExpectedAt()?->getTimestamp(),
  187. 'progress' => $this->getProgress(),
  188. ];
  189. }
  190. /**
  191. * @param string|null $error
  192. * @return void
  193. * @since 30.0.0
  194. */
  195. final public function setErrorMessage(?string $error) {
  196. $this->errorMessage = $error;
  197. }
  198. /**
  199. * @return string|null
  200. * @since 30.0.0
  201. */
  202. final public function getErrorMessage(): ?string {
  203. return $this->errorMessage;
  204. }
  205. /**
  206. * @param array $input
  207. * @return void
  208. * @since 30.0.0
  209. */
  210. final public function setInput(array $input): void {
  211. $this->input = $input;
  212. }
  213. /**
  214. * @param float|null $progress
  215. * @return void
  216. * @throws ValidationException
  217. * @since 30.0.0
  218. */
  219. final public function setProgress(?float $progress): void {
  220. if ($progress < 0 || $progress > 1.0) {
  221. throw new ValidationException('Progress must be between 0.0 and 1.0 inclusively; ' . $progress . ' given');
  222. }
  223. $this->progress = $progress;
  224. }
  225. /**
  226. * @return float|null
  227. * @since 30.0.0
  228. */
  229. final public function getProgress(): ?float {
  230. return $this->progress;
  231. }
  232. /**
  233. * @param int $status
  234. * @return 'STATUS_CANCELLED'|'STATUS_FAILED'|'STATUS_SUCCESSFUL'|'STATUS_RUNNING'|'STATUS_SCHEDULED'|'STATUS_UNKNOWN'
  235. * @since 30.0.0
  236. */
  237. final public static function statusToString(int $status): string {
  238. return match ($status) {
  239. self::STATUS_CANCELLED => 'STATUS_CANCELLED',
  240. self::STATUS_FAILED => 'STATUS_FAILED',
  241. self::STATUS_SUCCESSFUL => 'STATUS_SUCCESSFUL',
  242. self::STATUS_RUNNING => 'STATUS_RUNNING',
  243. self::STATUS_SCHEDULED => 'STATUS_SCHEDULED',
  244. default => 'STATUS_UNKNOWN',
  245. };
  246. }
  247. }