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) 2013 (original work) Open Assessment Technologies SA (under the project TAO-PRODUCT);
19	*
20	*/
21
22	use oat\taoResultServer\models\Exceptions\DuplicateVariableException;
23
24	/**
25	* The WritableResultStorage interface.
26	*
27	* The WritableResultStorage interface describes all the methods to write results of deliveries
28	* taken by test takers into a specific Result Server implementation.
29	*
30	* @author Joel Bout <joel@taotesting.com>
31	* @author Antoine Robin <antoine.robin@vesperiagroup.com>
32	* @author Jérôme Bogaerts <jerome@taotesting.com>
33	*
34	*/
35	interface taoResultServer_models_classes_WritableResultStorage
36	{
37	/**
38	* Spawn Result
39	*
40	* Initialize a new raw Delivery Result.
41	*
42	* After initialization, the Delivery Result will be empty, and will not be linked
43	* to a Test Taker or a Delivery.
44	*
45	* Please note that it is the responisibility of the implementer to generate Delivery
46	* Result identifiers that are as unique as possible.
47	*
48	* @return string The unique identifier of the initialized Delivery Result.
49	*/
50	public function spawnResult();
51
52	/**
53	* Store Related Test Taker
54	*
55	* Attach a given Test Taker to a Delivery Result.
56	*
57	* A Delivery Result is always attached to a single Test Taker. This method enables
58	* the client code to register a given Test Taker, using its $testTakerIdentifier, to a
59	* given Delivery Result, using its $deliveryResultIdentifier.
60	*
61	* @param string $deliveryResultIdentifier The identifier of the Delivery Result (usually a Delivery Execution URI).
62	* @param string $testTakerIdentifier The identifier of the Test Taker (usually a URI).
63	*/
64	public function storeRelatedTestTaker($deliveryResultIdentifier, $testTakerIdentifier);
65
66	/**
67	* Store Related Delivery
68	*
69	* Store a delivery related to a specific delivery execution
70	*
71	* @param string $deliveryResultIdentifier (mostly delivery execution uri)
72	* @param string $deliveryIdentifier (uri recommended)
73	*/
74	public function storeRelatedDelivery($deliveryResultIdentifier, $deliveryIdentifier);
75
76	/**
77	* Store Item Variable
78	*
79	* Submit a specific Item Variable, (ResponseVariable and OutcomeVariable shall be used respectively for collected
80	* data and score/interpretation computation) and store it with all the dependencies
81	*
82	* @param string $deliveryResultIdentifier
83	* @param string $test (uri recommended)
84	* @param string $item (uri recommended)
85	* @param taoResultServer_models_classes_Variable $itemVariable the variable to store
86	* @param string $callIdItem contextual call id for the variable, ex. :  to distinguish the same variable output
87	*                           by the same item and that is presented several times in the same test
88	* @throws DuplicateVariableException
89	*/
90	public function storeItemVariable(
91	$deliveryResultIdentifier,
92	$test,
93	$item,
94	taoResultServer_models_classes_Variable $itemVariable,
95	$callIdItem
96	);
97
98	/**
99	* @param $deliveryResultIdentifier
100	* @param $test
101	* @param $item
102	* @param array $itemVariables
103	* @param $callIdItem
104	* @return mixed
105	* @throws DuplicateVariableException
106	*/
107	public function storeItemVariables($deliveryResultIdentifier, $test, $item, array $itemVariables, $callIdItem);
108
109	/**
110	* Store Test Variable
111	*
112	* Submit a specific test Variable and store it
113	*
114	* @param string $deliveryResultIdentifier
115	* @param string $test
116	* @param taoResultServer_models_classes_Variable $testVariable
117	* @param $callIdTest
118	* @throws DuplicateVariableException
119	*/
120	public function storeTestVariable(
121	$deliveryResultIdentifier,
122	$test,
123	taoResultServer_models_classes_Variable $testVariable,
124	$callIdTest
125	);
126
127	/**
128	* @param $deliveryResultIdentifier
129	* @param $test
130	* @param array $testVariables
131	* @param $callIdTest
132	* @return mixed
133	* @throws DuplicateVariableException
134	*/
135	public function storeTestVariables($deliveryResultIdentifier, $test, array $testVariables, $callIdTest);
136
137	/**
138	* Configure
139	*
140	* The storage may configure itself based on the resultServer definition
141	*
142	* @param array $callOptions
143	*/
144	public function configure($callOptions = []);
145	}