1<?php
2/**
3 * @author Bart Visscher <bartv@thisnet.nl>
4 * @author Felix Moeller <mail@felixmoeller.de>
5 * @author Jakob Sack <mail@jakobsack.de>
6 * @author Joas Schilling <coding@schilljs.com>
7 * @author Jörn Friedrich Dreyer <jfd@butonic.de>
8 * @author Morris Jobke <hey@morrisjobke.de>
9 * @author Robin Appelman <icewind@owncloud.com>
10 * @author Robin McCorkell <robin@mccorkell.me.uk>
11 * @author Thomas Müller <thomas.mueller@tmit.eu>
12 *
13 * @copyright Copyright (c) 2018, ownCloud GmbH
14 * @license AGPL-3.0
15 *
16 * This code is free software: you can redistribute it and/or modify
17 * it under the terms of the GNU Affero General Public License, version 3,
18 * as published by the Free Software Foundation.
19 *
20 * This program is distributed in the hope that it will be useful,
21 * but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 * GNU Affero General Public License for more details.
24 *
25 * You should have received a copy of the GNU Affero General Public License, version 3,
26 * along with this program.  If not, see <http://www.gnu.org/licenses/>
27 *
28 */
29
30/**
31 * Public interface of ownCloud for background jobs.
32 */
33
34// use OCP namespace for all classes that are considered public.
35// This means that they should be used by apps instead of the internal ownCloud classes
36namespace OCP;
37
38/**
39 * This class provides functions to register backgroundjobs in ownCloud
40 *
41 * To create a new backgroundjob create a new class that inherits from either \OC\BackgroundJob\Job,
42 * \OC\BackgroundJob\QueuedJob or \OC\BackgroundJob\TimedJob and register it using
43 * \OCP\BackgroundJob->registerJob($job, $argument), $argument will be passed to the run() function
44 * of the job when the job is executed.
45 *
46 * A regular Job will be executed every time cron.php is run, a QueuedJob will only run once and a TimedJob
47 * will only run at a specific interval which is to be specified in the constructor of the job by calling
48 * $this->setInterval($interval) with $interval in seconds.
49 * @since 4.5.0
50 */
51class BackgroundJob {
52	/**
53	 * get the execution type of background jobs
54	 *
55	 * @return string
56	 *
57	 * This method returns the type how background jobs are executed. If the user
58	 * did not select something, the type is ajax.
59	 * @since 5.0.0
60	 */
61	public static function getExecutionType() {
62		return \OC::$server->getConfig()->getAppValue('core', 'backgroundjobs_mode', 'ajax');
63	}
64
65	/**
66	 * sets the background jobs execution type
67	 *
68	 * @param string $type execution type
69	 * @return false|null
70	 *
71	 * This method sets the execution type of the background jobs. Possible types
72	 * are "none", "ajax", "webcron", "cron"
73	 * @since 5.0.0
74	 */
75	public static function setExecutionType($type) {
76		if (!\in_array($type, ['none', 'ajax', 'webcron', 'cron'])) {
77			return false;
78		}
79		\OC::$server->getConfig()->setAppValue('core', 'backgroundjobs_mode', $type);
80	}
81
82	/**
83	 * @param string $job
84	 * @param mixed $argument
85	 * @deprecated 8.1.0 Use \OC::$server->getJobList()->add() instead
86	 * @since 6.0.0
87	 */
88	public static function registerJob($job, $argument = null) {
89		$jobList = \OC::$server->getJobList();
90		$jobList->add($job, $argument);
91	}
92
93	/**
94	 * @deprecated 6.0.0
95	 * creates a regular task
96	 * @param string $klass class name
97	 * @param string $method method name
98	 * @return boolean|null
99	 * @since 4.5.0
100	 */
101	public static function addRegularTask($klass, $method) {
102		if (!\OCP\Util::needUpgrade()) {
103			self::registerJob('OC\BackgroundJob\Legacy\RegularJob', [$klass, $method]);
104			return true;
105		}
106	}
107
108	/**
109	 * @deprecated 6.0.0
110	 * gets all regular tasks
111	 * @return array
112	 *
113	 * key is string "$klass-$method", value is array( $klass, $method )
114	 * @since 4.5.0
115	 */
116	public static function allRegularTasks() {
117		return [];
118	}
119
120	/**
121	 * @deprecated 6.0.0
122	 * Gets one queued task
123	 * @param int $id ID of the task
124	 * @return BackgroundJob\IJob|null
125	 * @since 4.5.0
126	 */
127	public static function findQueuedTask($id) {
128		$jobList = \OC::$server->getJobList();
129		return $jobList->getById($id);
130	}
131
132	/**
133	 * @deprecated 6.0.0
134	 * Gets all queued tasks
135	 * @return array an array of associative arrays
136	 * @since 4.5.0
137	 */
138	public static function allQueuedTasks() {
139		return [];
140	}
141
142	/**
143	 * @deprecated 6.0.0
144	 * Gets all queued tasks of a specific app
145	 * @param string $app app name
146	 * @return array an array of associative arrays
147	 * @since 4.5.0
148	 */
149	public static function queuedTaskWhereAppIs($app) {
150		return [];
151	}
152
153	/**
154	 * @deprecated 6.0.0
155	 * queues a task
156	 * @param string $app app name
157	 * @param string $class class name
158	 * @param string $method method name
159	 * @param string $parameters all useful data as text
160	 * @return boolean id of task
161	 * @since 4.5.0
162	 */
163	public static function addQueuedTask($app, $class, $method, $parameters) {
164		self::registerJob('OC\BackgroundJob\Legacy\QueuedJob', ['app' => $app, 'klass' => $class, 'method' => $method, 'parameters' => $parameters]);
165		return true;
166	}
167
168	/**
169	 * @deprecated 6.0.0
170	 * deletes a queued task
171	 * @param int $id id of task
172	 * @return boolean|null
173	 *
174	 * Deletes a report
175	 * @since 4.5.0
176	 */
177	public static function deleteQueuedTask($id) {
178		$jobList = \OC::$server->getJobList();
179		$job = $jobList->getById($id);
180		if ($job) {
181			$jobList->remove($job);
182		}
183	}
184}
185