[Summary 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   * Code for the submissions allocation support is defined here
  20   *
  21   * @package    mod_workshop
  22   * @copyright  2009 David Mudrak <david.mudrak@gmail.com>
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  defined('MOODLE_INTERNAL') || die();
  27  
  28  /**
  29   * Allocators are responsible for assigning submissions to reviewers for assessments
  30   *
  31   * The task of the allocator is to assign the correct number of submissions to reviewers
  32   * for assessment. Several allocation methods are expected and they can be combined. For
  33   * example, teacher can allocate several submissions manually (by 'manual' allocator) and
  34   * then let the other submissions being allocated randomly (by 'random' allocator).
  35   * Allocation is actually done by creating an initial assessment record in the
  36   * workshop_assessments table.
  37   */
  38  interface workshop_allocator {
  39  
  40      /**
  41       * Initialize the allocator and eventually process submitted data
  42       *
  43       * This method is called soon after the allocator is constructed and before any output
  44       * is generated. Therefore it may process any data submitted and do other tasks.
  45       * It must not produce any output.
  46       *
  47       * @throws moodle_exception
  48       * @return workshop_allocation_result
  49       */
  50      public function init();
  51  
  52      /**
  53       * Print HTML to be displayed as the user interface
  54       *
  55       * If a form is part of the UI, the caller should have called $PAGE->set_url(...)
  56       *
  57       * @param stdClass $wsoutput workshop module renderer can be used
  58       * @return string HTML code to be echoed
  59       */
  60      public function ui();
  61  
  62      /**
  63       * Delete all data related to a given workshop module instance
  64       *
  65       * This is called from {@link workshop_delete_instance()}.
  66       *
  67       * @param int $workshopid id of the workshop module instance being deleted
  68       * @return void
  69       */
  70      public static function delete_instance($workshopid);
  71  }
  72  
  73  
  74  /**
  75   * Stores the information about the allocation process
  76   *
  77   * Allocator's method init() returns instance of this class.
  78   */
  79  class workshop_allocation_result implements renderable {
  80  
  81      /** the init() called successfully but no actual allocation was done */
  82      const STATUS_VOID           = 0;
  83      /** allocation was successfully executed */
  84      const STATUS_EXECUTED       = 1;
  85      /** a serious error has occurred during the allocation (as a hole) */
  86      const STATUS_FAILED         = 2;
  87      /** scheduled allocation was configured (to be executed later, for example) */
  88      const STATUS_CONFIGURED     = 3;
  89  
  90      /** @var workshop_allocator the instance of the allocator that produced this result */
  91      protected $allocator;
  92      /** @var null|int the status of the init() call */
  93      protected $status = null;
  94      /** @var null|string optional result message to display */
  95      protected $message = null;
  96      /** @var int the timestamp of when the allocation process started */
  97      protected $timestart = null;
  98      /** @var int the timestamp of when the final status was set */
  99      protected $timeend = null;
 100      /** @var array of log message objects, {@see self::log()} */
 101      protected $logs = array();
 102  
 103      /**
 104       * Creates new instance of the object
 105       *
 106       * @param workshop_allocator $allocator
 107       */
 108      public function __construct(workshop_allocator $allocator) {
 109          $this->allocator = $allocator;
 110          $this->timestart = time();
 111      }
 112  
 113      /**
 114       * Sets the result status of the allocation
 115       *
 116       * @param int $status the status code, eg {@link self::STATUS_OK}
 117       * @param string $message optional status message
 118       */
 119      public function set_status($status, $message = null) {
 120          $this->status = $status;
 121          $this->message = is_null($message) ? $this->message : $message;
 122          $this->timeend = time();
 123      }
 124  
 125      /**
 126       * @return int|null the result status
 127       */
 128      public function get_status() {
 129          return $this->status;
 130      }
 131  
 132      /**
 133       * @return string|null status message
 134       */
 135      public function get_message() {
 136          return $this->message;
 137      }
 138  
 139      /**
 140       * @return int|null the timestamp of when the final status was set
 141       */
 142      public function get_timeend() {
 143          return $this->timeend;
 144      }
 145  
 146      /**
 147       * Appends a new message to the log
 148       *
 149       * The available levels are
 150       *  ok - success, eg. new allocation was created
 151       *  info - informational message
 152       *  error - error message, eg. no more peers available
 153       *  debug - debugging info
 154       *
 155       * @param string $message message text to display
 156       * @param string $type the type of the message
 157       * @param int $indent eventual indentation level (the message is related to the previous one with the lower indent)
 158       */
 159      public function log($message, $type = 'ok', $indent = 0) {
 160          $log = new stdClass();
 161          $log->message = $message;
 162          $log->type = $type;
 163          $log->indent = $indent;
 164  
 165          $this->logs[] = $log;
 166      }
 167  
 168      /**
 169       * Returns list of logged messages
 170       *
 171       * Each object in the list has public properties
 172       *  message string, text to display
 173       *  type string, the type of the message
 174       *  indent int, indentation level
 175       *
 176       * @see self::log()
 177       * @return array of log objects
 178       */
 179      public function get_logs() {
 180          return $this->logs;
 181      }
 182  }