3 // This file is part of Moodle - http://moodle.org/
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 // GNU General Public License for more details.
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
20 * @subpackage backup-plan
21 * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 * Abstract class defining the basis for one execution (backup/restore) task
28 * TODO: Finish phpdocs
30 abstract class base_task
implements checksumable
, executable
, loggable
{
32 protected $name; // One simple name for identification purposes
33 protected $plan; // Plan this is part of
34 protected $settings; // One array of base_setting elements to define this task
35 protected $steps; // One array of base_step elements
37 protected $built; // Flag to know if one task has been built
38 protected $executed; // Flag to know if one task has been executed
41 * Constructor - instantiates one object of this class
43 public function __construct($name, $plan = null) {
44 if (!is_null($plan) && !($plan instanceof base_plan
)) {
45 throw new base_task_exception('wrong_base_plan_specified');
49 $this->settings
= array();
50 $this->steps
= array();
52 $this->executed
= false;
53 if (!is_null($plan)) { // Add the task to the plan if specified
54 $plan->add_task($this);
58 public function get_name() {
62 public function get_steps() {
66 public function get_settings() {
67 return $this->settings
;
71 * Returns the weight of this task, an approximation of the amount of time
72 * it will take. By default this value is 1. It can be increased for longer
77 public function get_weight() {
81 public function get_setting($name) {
82 // First look in task settings
84 foreach ($this->settings
as $key => $setting) {
85 if ($setting->get_name() == $name) {
86 if ($result != null) {
87 throw new base_task_exception('multiple_settings_by_name_found', $name);
96 // Fallback to plan settings
97 return $this->plan
->get_setting($name);
101 public function setting_exists($name) {
102 return $this->plan
->setting_exists($name);
105 public function get_setting_value($name) {
106 return $this->get_setting($name)->get_value();
109 public function get_courseid() {
110 return $this->plan
->get_courseid();
113 public function get_basepath() {
114 return $this->plan
->get_basepath();
117 public function get_taskbasepath() {
118 return $this->get_basepath();
121 public function get_logger() {
122 return $this->plan
->get_logger();
126 * Gets the progress reporter, which can be used to report progress within
127 * the backup or restore process.
129 * @return \core\progress\base Progress reporting object
131 public function get_progress() {
132 return $this->plan
->get_progress();
135 public function log($message, $level, $a = null, $depth = null, $display = false) {
136 backup_helper
::log($message, $level, $a, $depth, $display, $this->get_logger());
139 public function add_step($step) {
140 if (! $step instanceof base_step
) {
141 throw new base_task_exception('wrong_base_step_specified');
143 // link the step with the task
144 $step->set_task($this);
145 $this->steps
[] = $step;
148 public function set_plan($plan) {
149 if (! $plan instanceof base_plan
) {
150 throw new base_task_exception('wrong_base_plan_specified');
153 $this->define_settings(); // Settings are defined when plan & task are linked
157 * Function responsible for building the steps of any task
158 * (must set the $built property to true)
160 public abstract function build();
163 * Function responsible for executing the steps of any task
164 * (setting the $executed property to true)
166 public function execute() {
168 throw new base_task_exception('base_task_not_built', $this->name
);
170 if ($this->executed
) {
171 throw new base_task_exception('base_task_already_executed', $this->name
);
174 // Starts progress based on the weight of this task and number of steps.
175 $progress = $this->get_progress();
176 $progress->start_progress($this->get_name(), count($this->steps
), $this->get_weight());
179 // Execute all steps.
180 foreach ($this->steps
as $step) {
181 $result = $step->execute();
182 // If step returns array, it will be forwarded to plan
183 // (TODO: shouldn't be array but proper result object)
184 if (is_array($result) and !empty($result)) {
185 $this->add_result($result);
188 $progress->progress($done);
190 // Mark as executed if any step has been executed
191 if (!empty($this->steps
)) {
192 $this->executed
= true;
195 // Finish progress for this task.
196 $progress->end_progress();
200 * Destroy all circular references. It helps PHP 5.2 a lot!
202 public function destroy() {
203 // Before reseting anything, call destroy recursively
204 foreach ($this->steps
as $step) {
207 foreach ($this->settings
as $setting) {
210 // Everything has been destroyed recursively, now we can reset safely
211 $this->steps
= array();
212 $this->settings
= array();
216 public function is_checksum_correct($checksum) {
217 return $this->calculate_checksum() === $checksum;
220 public function calculate_checksum() {
221 // Let's do it using name and settings and steps
222 return md5($this->name
. '-' .
223 backup_general_helper
::array_checksum_recursive($this->settings
) .
224 backup_general_helper
::array_checksum_recursive($this->steps
));
228 * Add the given info to the current plan's results.
230 * @see base_plan::add_result()
231 * @param array $result associative array describing a result of a task/step
233 public function add_result($result) {
234 if (!is_null($this->plan
)) {
235 $this->plan
->add_result($result);
237 debugging('Attempting to add a result of a task not binded with a plan', DEBUG_DEVELOPER
);
242 * Return the current plan's results
246 public function get_results() {
247 if (!is_null($this->plan
)) {
248 return $this->plan
->get_results();
250 debugging('Attempting to get results of a task not binded with a plan', DEBUG_DEVELOPER
);
255 // Protected API starts here
258 * This function is invoked on activity creation in order to add all the settings
259 * that are associated with one task. The function will, directly, inject the settings
262 protected abstract function define_settings();
264 protected function add_setting($setting) {
265 if (! $setting instanceof base_setting
) {
266 throw new base_setting_exception('wrong_base_setting_specified');
268 $this->settings
[] = $setting;
273 * Exception class used by all the @base_task stuff
275 class base_task_exception
extends moodle_exception
{
277 public function __construct($errorcode, $a=NULL, $debuginfo=null) {
278 parent
::__construct($errorcode, '', '', $a, $debuginfo);