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) 2016 (original work) Open Assessment Technologies SA ;
19	*/
20
21	/**
22	* @author Jean-Sébastien Conan <jean-sebastien.conan@vesperiagroup.com>
23	*/
24
25	namespace oat\taoQtiTest\models\runner;
26
27	use oat\taoQtiTest\models\runner\config\RunnerConfig;
28	use qtism\data\AssessmentItemRef;
29	use oat\taoDelivery\model\execution\Delete\DeliveryExecutionDelete;
30
31	/**
32	* Interface RunnerService
33	*
34	* Describes a test runner dedicated service
35	*
36	* @package oat\taoQtiTest\models
37	*/
38	interface RunnerService extends DeliveryExecutionDelete
39	{
40	public const INSTANCE_TEST_RUNNER_SERVICE = 'http://www.tao.lu/Ontologies/TAODelivery.rdf#ServiceQtiTestRunner';
41
42	// phpcs:disable Generic.Files.LineLength
43	public const INSTANCE_TEST_ITEM_RUNNER_SERVICE = 'http://www.tao.lu/Ontologies/TAODelivery.rdf#ServiceQtiTestItemRunner';
44	// phpcs:enable Generic.Files.LineLength
45
46	// phpcs:disable Generic.Files.LineLength
47	public const INSTANCE_FORMAL_PARAM_TEST_ITEM_RUNNER_PARENT_CALL_ID = 'http://www.tao.lu/Ontologies/TAOTest.rdf#FormalParamQtiTestParentServiceCallId';
48	// phpcs:enable Generic.Files.LineLength
49
50	/**
51	* Initializes the delivery execution session
52	* @param RunnerServiceContext $context
53	* @return boolean
54	* @throws \common_Exception
55	*/
56	public function init(RunnerServiceContext $context);
57
58	/**
59	* Gets the test runner config
60	* @return RunnerConfig
61	* @throws \common_ext_ExtensionException
62	*/
63	public function getTestConfig();
64
65	/**
66	* Gets the test definition data
67	*
68	* @deprecated the testData is not necessary anymore
69	* if the config is given directly to the test runner configuration
70	*
71	* @param RunnerServiceContext $context
72	* @return array
73	* @throws \common_Exception
74	*/
75	public function getTestData(RunnerServiceContext $context);
76
77	/**
78	* Gets the test context object
79	* @param RunnerServiceContext $context
80	* @return array
81	* @throws \common_Exception
82	*/
83	public function getTestContext(RunnerServiceContext $context);
84
85	/**
86	* Gets the map of the test items
87	* @param RunnerServiceContext $context
88	* @param bool $partial the full testMap or only the current section
89	* @return array
90	* @throws \common_Exception
91	*/
92	public function getTestMap(RunnerServiceContext $context, $partial = false);
93
94	/**
95	* Gets the rubrics related to the current session state
96	* @param RunnerServiceContext $context
97	* @param AssessmentItemRef $itemRef (optional) otherwise use the current
98	* @return mixed
99	* @throws \common_Exception
100	*/
101	public function getRubrics(RunnerServiceContext $context, AssessmentItemRef $itemRef = null);
102
103	/**
104	* Gets definition data of a particular item
105	* @param RunnerServiceContext $context
106	* @param $itemRef
107	* @return mixed
108	* @throws \common_Exception
109	*/
110	public function getItemData(RunnerServiceContext $context, $itemRef);
111
112	/**
113	* Gets the state of a particular item
114	* @param RunnerServiceContext $context
115	* @param $itemRef
116	* @return array|null
117	* @throws \common_Exception
118	*/
119	public function getItemState(RunnerServiceContext $context, $itemRef);
120
121	/**
122	* Sets the state of a particular item
123	* @param RunnerServiceContext $context
124	* @param $itemRef
125	* @param $state
126	* @return boolean
127	* @throws \common_Exception
128	*/
129	public function setItemState(RunnerServiceContext $context, $itemRef, $state);
130
131	/**
132	* Parses the responses provided for a particular item
133	* @param RunnerServiceContext $context
134	* @param $itemRef
135	* @param $response
136	* @return mixed
137	* @throws \common_Exception
138	*/
139	public function parsesItemResponse(RunnerServiceContext $context, $itemRef, $response);
140
141	/**
142	* Checks if the provided responses are empty
143	* @param RunnerServiceContext $context
144	* @param $responses
145	* @return mixed
146	* @throws \common_Exception
147	*/
148	public function emptyResponse(RunnerServiceContext $context, $responses);
149
150	/**
151	* Stores the responses of a particular item
152	* @param RunnerServiceContext $context
153	* @param $itemRef
154	* @param $responses
155	* @return boolean
156	* @throws \common_Exception
157	*/
158	public function storeItemResponse(RunnerServiceContext $context, $itemRef, $responses);
159
160	/**
161	* Should we display feedbacks
162	* @param RunnerServiceContext $context
163	* @return boolean
164	* @throws \common_Exception
165	*/
166	public function displayFeedbacks(RunnerServiceContext $context);
167
168	/**
169	* Get feedback definition
170	* @param RunnerServiceContext $context
171	* @param string $itemRef  the item reference
172	* @return array the feedbacks data
173	* @throws \common_exception_InvalidArgumentType
174	*/
175	public function getFeedbacks(RunnerServiceContext $context, $itemRef);
176
177	/**
178	* Does the given item has feedbacks
179	* @param RunnerServiceContext $context
180	* @param string $itemRef  the item reference
181	* @return boolean
182	* @throws \common_Exception
183	*/
184	public function hasFeedbacks(RunnerServiceContext $context, $itemRef);
185
186	/**
187	* Get the current item session
188	* @param RunnerServiceContext $context
189	* @throws \common_Exception
190	*/
191	public function getItemSession(RunnerServiceContext $context);
192
193	/**
194	* Moves the current position to the provided scoped reference.
195	* @param RunnerServiceContext $context
196	* @param $direction
197	* @param $scope
198	* @param $ref
199	* @return boolean
200	* @throws \common_Exception
201	*/
202	public function move(RunnerServiceContext $context, $direction, $scope, $ref);
203
204	/**
205	* Skips the current position to the provided scoped reference
206	* @param RunnerServiceContext $context
207	* @param $scope
208	* @param $ref
209	* @return boolean
210	* @throws \common_Exception
211	*/
212	public function skip(RunnerServiceContext $context, $scope, $ref);
213
214	/**
215	* Handles a test timeout
216	* @param RunnerServiceContext $context
217	* @param $scope
218	* @param $ref
219	* @return boolean
220	* @throws \common_Exception
221	*/
222	public function timeout(RunnerServiceContext $context, $scope, $ref);
223
224	/**
225	* Exits the test before its end
226	* @param RunnerServiceContext $context
227	* @return boolean
228	* @throws \common_Exception
229	*/
230	public function exitTest(RunnerServiceContext $context);
231
232	/**
233	* Finishes the test
234	* @param RunnerServiceContext $context
235	* @return boolean
236	* @throws \common_Exception
237	*/
238	public function finish(RunnerServiceContext $context);
239
240	/**
241	* Sets the test to paused state
242	* @param RunnerServiceContext $context
243	* @return boolean
244	* @throws \common_Exception
245	*/
246	public function pause(RunnerServiceContext $context);
247
248	/**
249	* Resumes the test from paused state
250	* @param RunnerServiceContext $context
251	* @return boolean
252	* @throws \common_Exception
253	*/
254	public function resume(RunnerServiceContext $context);
255
256	/**
257	* Checks if the test is still valid
258	* @param RunnerServiceContext $context
259	* @return boolean
260	* @throws \common_Exception
261	*/
262	public function check(RunnerServiceContext $context);
263
264	/**
265	* Checks if the test is in paused state
266	* @param RunnerServiceContext $context
267	* @return boolean
268	*/
269	public function isPaused(RunnerServiceContext $context);
270
271	/**
272	* Checks if the test is in terminated state
273	* @param RunnerServiceContext $context
274	* @return boolean
275	*/
276	public function isTerminated(RunnerServiceContext $context);
277
278	/**
279	* Get the list of portable elements used in the item
280	* @param RunnerServiceContext $context
281	* @param $itemRef
282	* @return mixed
283	*/
284	public function getItemPortableElements(RunnerServiceContext $context, $itemRef);
285
286	/**
287	* Get the list of metadata elements used in the item
288	* @param $itemRef
289	* @return mixed
290	*/
291	public function getItemMetadataElements($itemRef);
292
293	/**
294	* Gets AssessmentItemRef's Href by AssessmentItemRef Identifier.
295	* @param RunnerServiceContext $context
296	* @param string $itemRef
297	* @return string
298	*/
299	public function getItemHref(RunnerServiceContext $context, string $itemRef): string;
300
301	/**
302	* Get the base url to the item public directory
303	* @param RunnerServiceContext $context
304	* @param string $itemRef
305	* @return string
306	*/
307	public function getItemPublicUrl(RunnerServiceContext $context, string $itemRef): string;
308
309	/**
310	* Starts the timer for the current item in the TestSession
311	* @param RunnerServiceContext $context
312	* @param float|null $timestamp allow to start the timer at a specific time, or use current when it's null
313	* @return bool
314	* @throws \common_exception_InvalidArgumentType
315	*/
316	public function startTimer(RunnerServiceContext $context, ?float $timestamp = null): bool;
317
318	/**
319	* Ends the timer for the current item in the TestSession
320	* @param RunnerServiceContext $context
321	* @param float|null $duration The client side duration to adjust the timer
322	* @param float|null $timestamp allow to end the timer at a specific time, or use current when it's null
323	* @return bool
324	* @throws \common_exception_InvalidArgumentType
325	*/
326	public function endTimer(RunnerServiceContext $context, ?float $duration = null, ?float $timestamp = null): bool;
327
328	/**
329	* Stores trace variable related to an item, a test or a section
330	*
331	* @param RunnerServiceContext $context
332	* @param string|null $itemUri
333	* @param string $variableIdentifier
334	* @param mixed $variableValue
335	* @return boolean
336	* @throws \common_Exception
337	*/
338	public function storeTraceVariable(
339	RunnerServiceContext $context,
340	?string $itemUri,
341	string $variableIdentifier,
342	$variableValue
343	): bool;
344	}