[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  // This file is part of Moodle - http://moodle.org/
   4  //
   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.
   9  //
  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.
  14  //
  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/>.
  17  
  18  /**
  19   * @package moodlecore
  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
  23   */
  24  
  25  /**
  26   * Abstract class defining the basis for one execution (backup/restore) plan
  27   *
  28   * TODO: Finish phpdocs
  29   */
  30  abstract class base_plan implements checksumable, executable {
  31  
  32      protected $name;      // One simple name for identification purposes
  33      protected $settings;  // One array of (accumulated from tasks) base_setting elements
  34      protected $tasks;     // One array of base_task elements
  35      protected $results;   // One array of results received from tasks
  36  
  37      protected $built;     // Flag to know if one plan has been built
  38  
  39      /**
  40       * Constructor - instantiates one object of this class
  41       */
  42      public function __construct($name) {
  43          $this->name = $name;
  44          $this->settings = array();
  45          $this->tasks    = array();
  46          $this->results  = array();
  47          $this->built = false;
  48      }
  49  
  50      public function get_name() {
  51          return $this->name;
  52      }
  53  
  54      public function add_task($task) {
  55          if (! $task instanceof base_task) {
  56              throw new base_plan_exception('wrong_base_task_specified');
  57          }
  58          $this->tasks[] = $task;
  59          // link the task with the plan
  60          $task->set_plan($this);
  61          // Append task settings to plan array, if not present, for comodity
  62          foreach ($task->get_settings() as $key => $setting) {
  63              // Check if there is already a setting for this name.
  64              $name = $setting->get_name();
  65              if (!isset($this->settings[$name])) {
  66                  // There is no setting, so add it.
  67                  $this->settings[$name] = $setting;
  68              } else if ($this->settings[$name] != $setting) {
  69                  // If the setting already exists AND it is not the same setting,
  70                  // then throw an error. (I.e. you're allowed to add the same
  71                  // setting twice, but cannot add two different ones with same
  72                  // name.)
  73                  throw new base_plan_exception('multiple_settings_by_name_found', $name);
  74              }
  75          }
  76      }
  77  
  78      public function get_tasks() {
  79          return $this->tasks;
  80      }
  81  
  82      /**
  83       * Add the passed info to the plan results
  84       *
  85       * At the moment we expect an associative array structure to be merged into
  86       * the current results. In the future, some sort of base_result class may
  87       * be introduced.
  88       *
  89       * @param array $result associative array describing a result of a task/step
  90       */
  91      public function add_result($result) {
  92          if (!is_array($result)) {
  93              throw new coding_exception('Associative array is expected as a parameter of add_result()');
  94          }
  95          $this->results = array_merge($this->results, $result);
  96      }
  97  
  98      /**
  99       * Return the results collected via {@link self::add_result()} method
 100       *
 101       * @return array
 102       */
 103      public function get_results() {
 104          return $this->results;
 105      }
 106  
 107      public function get_settings() {
 108          return $this->settings;
 109      }
 110  
 111      /**
 112       * return one setting by name, useful to request root/course settings
 113       * that are, by definition, unique by name.
 114       *
 115       * @param string $name name of the setting
 116       * @throws base_plan_exception if setting name is not found.
 117       */
 118      public function get_setting($name) {
 119          $result = null;
 120          if (isset($this->settings[$name])) {
 121              $result = $this->settings[$name];
 122          } else {
 123              throw new base_plan_exception('setting_by_name_not_found', $name);
 124          }
 125          return $result;
 126      }
 127  
 128      /**
 129       * Wrapper over @get_setting() that returns if the requested setting exists or no
 130       */
 131      public function setting_exists($name) {
 132          try {
 133              $this->get_setting($name);
 134              return true;
 135          } catch (base_plan_exception $e) {
 136              // Nothing to do
 137          }
 138          return false;
 139      }
 140  
 141  
 142      /**
 143       * Function responsible for building the tasks of any plan
 144       * with their corresponding settings
 145       * (must set the $built property to true)
 146       */
 147      public abstract function build();
 148  
 149      public function is_checksum_correct($checksum) {
 150          return $this->calculate_checksum() === $checksum;
 151      }
 152  
 153      public function calculate_checksum() {
 154          // Let's do it using name and tasks (settings are part of tasks)
 155          return md5($this->name . '-' . backup_general_helper::array_checksum_recursive($this->tasks));
 156      }
 157  
 158      /**
 159       * Function responsible for executing the tasks of any plan
 160       */
 161      public function execute() {
 162          if (!$this->built) {
 163              throw new base_plan_exception('base_plan_not_built');
 164          }
 165  
 166          // Calculate the total weight of all tasks and start progress tracking.
 167          $progress = $this->get_progress();
 168          $totalweight = 0;
 169          foreach ($this->tasks as $task) {
 170              $totalweight += $task->get_weight();
 171          }
 172          $progress->start_progress($this->get_name(), $totalweight);
 173  
 174          // Build and execute all tasks.
 175          foreach ($this->tasks as $task) {
 176              $task->build();
 177              $task->execute();
 178          }
 179  
 180          // Finish progress tracking.
 181          $progress->end_progress();
 182      }
 183  
 184      /**
 185       * Gets the progress reporter, which can be used to report progress within
 186       * the backup or restore process.
 187       *
 188       * @return \core\progress\base Progress reporting object
 189       */
 190      public abstract function get_progress();
 191  
 192      /**
 193       * Destroy all circular references. It helps PHP 5.2 a lot!
 194       */
 195      public function destroy() {
 196          // Before reseting anything, call destroy recursively
 197          foreach ($this->tasks as $task) {
 198              $task->destroy();
 199          }
 200          foreach ($this->settings as $setting) {
 201              $setting->destroy();
 202          }
 203          // Everything has been destroyed recursively, now we can reset safely
 204          $this->tasks = array();
 205          $this->settings = array();
 206      }
 207  }
 208  
 209  
 210  /*
 211   * Exception class used by all the @base_plan stuff
 212   */
 213  class base_plan_exception extends moodle_exception {
 214  
 215      public function __construct($errorcode, $a=NULL, $debuginfo=null) {
 216          parent::__construct($errorcode, '', '', $a, $debuginfo);
 217      }
 218  }