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\taoTests\models\runner\time;
26
27	/**
28	* Interface Timer
29	*
30	* Describes the API needed to build and manage a timer.
31	* A Timer is represented by a TimeLine on which it will apply actions and constraints.
32	* The actions are:
33	* - add time ranges by setting start and end TimePoints (SERVER)
34	* - adjust time ranges by settings intermediate start and end TimePoint (CLIENT)
35	* - compute duration for particular targets (SERVER or CLIENT)
36	*
37	* The constraints are:
38	* - coherence of time ranges
39	* - time limits and timeouts
40	*
41	* A timer is also responsible of its storage.
42	*
43	* @package oat\taoTests\models\runner\time
44	*/
45	interface Timer
46	{
47	/**
48	* Adds a "server start" TimePoint at a particular timestamp for the provided tags
49	* @param string|array $tags
50	* @param float $timestamp
51	* @return Timer
52	* @throws TimeException
53	*/
54	public function start($tags, $timestamp);
55
56	/**
57	* Adds a "server end" TimePoint at a particular timestamp for the provided tags
58	* @param string|array $tags
59	* @param float $timestamp
60	* @return Timer
61	* @throws TimeException
62	*/
63	public function end($tags, $timestamp);
64
65	/**
66	* Gets the first timestamp of the range for the provided tags
67	* @param string|array $tags
68	* @return float $timestamp
69	*/
70	public function getFirstTimestamp($tags);
71
72	/**
73	* Gets the last timestamp of the range for the provided tags
74	* @param string|array $tags
75	* @return float $timestamp
76	*/
77	public function getLastTimestamp($tags);
78
79	/**
80	* Adds "client start" and "client end" TimePoint based on the provided duration for particular tags
81	* @param string|array $tags
82	* @param float $duration
83	* @return Timer
84	* @throws TimeException
85	*/
86	public function adjust($tags, $duration);
87
88	/**
89	* Computes the total duration represented by the filtered TimePoints
90	* @param string|array $tags A tag or a list of tags to filter
91	* @param int $target The type of target TimePoint to filter
92	* @return float Returns the total computed duration
93	* @throws TimeException
94	*/
95	public function compute($tags, $target);
96
97	/**
98	* Checks if the duration of a TimeLine subset reached the timeout
99	* @param float $timeLimit The time limit against which compare the duration
100	* @param string|array $tags A tag or a list of tags to filter
101	* @param int $target The type of target TimePoint to filter
102	* @return bool Returns true if the timeout is reached
103	* @throws TimeException
104	*/
105	public function timeout($timeLimit, $tags, $target);
106
107	/**
108	* Sets the storage used to maintain the data
109	* @param TimeStorage $storage
110	* @return Timer
111	*/
112	public function setStorage(TimeStorage $storage);
113
114	/**
115	* @param TimerStrategyInterface $strategy
116	* @return Timer
117	*/
118	public function setStrategy(TimerStrategyInterface $strategy);
119
120	/**
121	* Gets the storage used to maintain the data
122	* @return TimeStorage
123	*/
124	public function getStorage();
125
126	/**
127	* Saves the data to the storage
128	* @return Timer
129	* @throws \Exception if any error occurs
130	*/
131	public function save();
132
133	/**
134	* Loads the data from the storage
135	* @return Timer
136	* @throws \Exception if any error occurs
137	*/
138	public function load();
139
140	/**
141	* @return mixed
142	* @throws \Exception
143	*/
144	public function delete();
145	}