1	<?php
2
3	/**
4	* This program is free software; you can redistribute it and/or
5	* modify it under the terms of the GNU General Public License
6	* as published by the Free Software Foundation; under version 2
7	* of the License (non-upgradable).
8	*
9	* This program is distributed in the hope that it will be useful,
10	* but WITHOUT ANY WARRANTY; without even the implied warranty of
11	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12	* GNU General Public License for more details.
13	*
14	* You should have received a copy of the GNU General Public License
15	* along with this program; if not, write to the Free Software
16	* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
17	*
18	* Copyright (c) 2017 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
19	*
20	*/
21
22	namespace oat\tao\model\taskQueue;
23
24	use common_report_Report as Report;
25	use oat\tao\model\taskQueue\Task\TaskInterface;
26	use oat\tao\model\taskQueue\TaskLog\Broker\TaskLogBrokerInterface;
27	use oat\tao\model\taskQueue\TaskLog\DataTablePayload;
28	use oat\tao\model\taskQueue\TaskLog\Entity\EntityInterface;
29	use oat\tao\model\taskQueue\TaskLog\CollectionInterface;
30	use oat\tao\model\taskQueue\TaskLog\TaskLogFilter;
31	use oat\tao\model\taskQueue\TaskLog\TasksLogsStats;
32	use oat\tao\model\datatable\DatatableRequest as DatatableRequestInterface;
33	use Psr\Log\LoggerAwareInterface;
34	use Datetime;
35
36	/**
37	* @author Gyula Szucs <gyula@taotesting.com>
38	*/
39	interface TaskLogInterface extends LoggerAwareInterface
40	{
41	public const SERVICE_ID = 'tao/taskLog';
42
43	public const OPTION_TASK_LOG_BROKER = 'task_log_broker';
44
45	/**
46	* An array of tasks names with the specified category.
47	*/
48	public const OPTION_TASK_TO_CATEGORY_ASSOCIATIONS = 'task_to_category_associations';
49
50	public const OPTION_TASK_IGNORE_LIST = 'task_ui_ignore_list';
51
52	public const STATUS_ENQUEUED = 'enqueued';
53	public const STATUS_DEQUEUED = 'dequeued';
54	public const STATUS_RUNNING = 'running';
55	public const STATUS_CHILD_RUNNING = 'child_running';
56	public const STATUS_COMPLETED = 'completed';
57	public const STATUS_FAILED = 'failed';
58	public const STATUS_ARCHIVED = 'archived';
59	public const STATUS_CANCELLED = 'cancelled';
60	public const STATUS_UNKNOWN = 'unknown';
61
62	public const CATEGORY_UNKNOWN = 'unknown';
63	public const CATEGORY_IMPORT = 'import';
64	public const CATEGORY_EXPORT = 'export';
65	public const CATEGORY_DELIVERY_COMPILATION = 'delivery_comp';
66	public const CATEGORY_CREATE = 'create';
67	public const CATEGORY_UPDATE = 'update';
68	public const CATEGORY_DELETE = 'delete';
69	public const CATEGORY_COPY = 'copy';
70	public const CATEGORY_UNRELATED_RESOURCE = 'unrelated_resource';
71
72	public const DEFAULT_LIMIT = 20;
73
74	public const OPTION_DEFAULT_BATCH_SIZE = 'default_batch_size';
75	public const DEFAULT_BATCH_SIZE = 1000;
76
77	/**
78	* It's not related to the user management, just a placeholder to distinguish the user running the script from CLI.
79	*/
80	public const SUPER_USER = 'cli-user';
81
82	/**
83	* @return void
84	*/
85	public function createContainer();
86
87	/**
88	* Insert a new task with status into the container.
89	*
90	* @param TaskInterface $task
91	* @param string        $status
92	* @param null|string   $label
93	* @return TaskLogInterface
94	*/
95	public function add(TaskInterface $task, $status, $label = null);
96
97	/**
98	* Set a status for a task.
99	*
100	* @param string $taskId
101	* @param string $newStatus
102	* @param string|null $prevStatus
103	* @return int
104	*/
105	public function setStatus($taskId, $newStatus, $prevStatus = null);
106
107	/**
108	* Gets the status of a task.
109	*
110	* @param string $taskId
111	* @return string
112	*/
113	public function getStatus($taskId);
114
115	/**
116	* Saves the report, status and redirect url for a task.
117	*
118	* @param string $taskId
119	* @param Report $report
120	* @param string|null $newStatus
121	* @return TaskLogInterface
122	*/
123	public function setReport($taskId, Report $report, $newStatus = null);
124
125	/**
126	* Gets the report for a task if that exists.
127	*
128	* @param string $taskId
129	* @return Report|null
130	*/
131	public function getReport($taskId);
132
133	/**
134	* Updates the parent task.
135	*
136	* @param string $parentTaskId
137	* @return TaskLogInterface
138	*/
139	public function updateParent($parentTaskId);
140
141	/**
142	* @param TaskLogFilter $filter
143	* @return CollectionInterface|EntityInterface[]
144	*/
145	public function search(TaskLogFilter $filter);
146
147	/**
148	* @param TaskLogFilter             $filter
149	* @param DatatableRequestInterface $request
150	* @return DataTablePayload
151	*/
152	public function getDataTablePayload(TaskLogFilter $filter, DatatableRequestInterface $request);
153
154	/**
155	* @param string $userId
156	* @param null   $limit
157	* @param null   $offset
158	* @return CollectionInterface|EntityInterface[]
159	*/
160	public function findAvailableByUser($userId, $limit = null, $offset = null);
161
162	/**
163	* @param string $userId
164	* @return TasksLogsStats
165	*/
166	public function getStats($userId);
167
168	/**
169	* @param string $taskId
170	* @return EntityInterface
171	*
172	* @throws \common_exception_NotFound
173	*/
174	public function getById($taskId);
175
176	/**
177	* @param string $taskId
178	* @param string $userId
179	* @param bool   $archivedAllowed
180	* @return EntityInterface
181	*
182	*/
183	public function getByIdAndUser($taskId, $userId, $archivedAllowed = false);
184
185	/**
186	* @param EntityInterface $entity
187	* @param bool $forceArchive
188	* @return bool
189	*
190	* @throws \Exception
191	*/
192	public function archive(EntityInterface $entity, $forceArchive = false);
193
194	/**
195	* @param CollectionInterface $collection
196	* @param bool                $forceArchive
197	* @return bool
198	*/
199	public function archiveCollection(CollectionInterface $collection, $forceArchive = false);
200
201	/**
202	* @param EntityInterface $entity
203	* @param bool            $forceCancel
204	* @return bool
205	*
206	* @throws \Exception
207	*/
208	public function cancel(EntityInterface $entity, $forceCancel = false);
209
210	/**
211	* @param CollectionInterface $collection
212	* @param bool                $forceCancel
213	* @return bool
214	*/
215	public function cancelCollection(CollectionInterface $collection, $forceCancel = false);
216
217	/**
218	* Gets the current broker instance.
219	*
220	* @return TaskLogBrokerInterface
221	*/
222	public function getBroker();
223
224	/**
225	* Is the current broker RDS based?
226	*
227	* @return bool
228	*/
229	public function isRds();
230
231	/**
232	* Link a task to a category.
233	*
234	* @param string|object $taskName
235	* @param string $category
236	* @return QueueDispatcherInterface
237	*/
238	public function linkTaskToCategory($taskName, $category);
239
240	/**
241	* Returns the defined category for a task.
242	*
243	* @param string|object $taskName
244	* @return string
245	*/
246	public function getCategoryForTask($taskName);
247
248	/**
249	* Returns the possible categories for a task.
250	*
251	* @return array
252	*/
253	public function getTaskCategories();
254
255	/**
256	* Fetch task execution times for given date range
257	* Formatted with task id as key and execution time as value
258	*
259	* @param DateTime $from
260	* @param DateTime $to
261	* @return array [ 'task1'=> 'time-in-second', 'task-id-1' => 10]`
262	*/
263	public function getTaskExecutionTimesByDateRange(DateTime $from, DateTime $to): array;
264	}