includes/jobqueue/JobSpecification.php

   1 <?php
   2 /**
   3  * Job queue task description base code.
   4  *
   5  * This program 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 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program 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 along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup JobQueue
  22  */
  23
  24 /**
  25  * Job queue task description interface
  26  *
  27  * @ingroup JobQueue
  28  * @since 1.23
  29  */
  30 interface IJobSpecification {
  31         /**
  32          * @return string Job type
  33          */
  34         public function getType();
  35
  36         /**
  37          * @return array
  38          */
  39         public function getParams();
  40
  41         /**
  42          * @return int|null UNIX timestamp to delay running this job until, otherwise null
  43          */
  44         public function getReleaseTimestamp();
  45
  46         /**
  47          * @return bool Whether only one of each identical set of jobs should be run
  48          */
  49         public function ignoreDuplicates();
  50
  51         /**
  52          * Subclasses may need to override this to make duplication detection work.
  53          * The resulting map conveys everything that makes the job unique. This is
  54          * only checked if ignoreDuplicates() returns true, meaning that duplicate
  55          * jobs are supposed to be ignored.
  56          *
  57          * @return array Map of key/values
  58          */
  59         public function getDeduplicationInfo();
  60
  61         /**
  62          * @return Title Descriptive title (this can simply be informative)
  63          */
  64         public function getTitle();
  65 }
  66
  67 /**
  68  * Job queue task description base code
  69  *
  70  * Example usage:
  71  * @code
  72  * $job = new JobSpecification(
  73  *              'null',
  74  *              array( 'lives' => 1, 'usleep' => 100, 'pi' => 3.141569 ),
  75  *              array( 'removeDuplicates' => 1 ),
  76  *              Title::makeTitle( NS_SPECIAL, 'nullity' )
  77  * );
  78  * JobQueueGroup::singleton()->push( $job )
  79  * @endcode
  80  *
  81  * @ingroup JobQueue
  82  * @since 1.23
  83  */
  84 class JobSpecification implements IJobSpecification {
  85         /** @var string */
  86         protected $type;
  87
  88         /** @var array Array of job parameters or false if none */
  89         protected $params;
  90
  91         /** @var Title */
  92         protected $title;
  93
  94         /** @var array */
  95         protected $opts;
  96
  97         /**
  98          * @param string $type
  99          * @param array $params Map of key/values
 100          * @param array $opts Map of key/values; includes 'removeDuplicates'
 101          * @param Title $title Optional descriptive title
 102          */
 103         public function __construct(
 104                 $type, array $params, array $opts = array(), Title $title = null
 105         ) {
 106                 $this->validateParams( $params );
 107                 $this->validateParams( $opts );
 108
 109                 $this->type = $type;
 110                 $this->params = $params;
 111                 $this->title = $title ?: Title::makeTitle( NS_SPECIAL, 'Badtitle/' . get_class( $this ) );
 112                 $this->opts = $opts;
 113         }
 114
 115         /**
 116          * @param array $params
 117          */
 118         protected function validateParams( array $params ) {
 119                 foreach ( $params as $p => $v ) {
 120                         if ( is_array( $v ) ) {
 121                                 $this->validateParams( $v );
 122                         } elseif ( !is_scalar( $v ) && $v !== null ) {
 123                                 throw new UnexpectedValueException( "Job parameter $p is not JSON serializable." );
 124                         }
 125                 }
 126         }
 127
 128         /**
 129          * @return string
 130          */
 131         public function getType() {
 132                 return $this->type;
 133         }
 134
 135         /**
 136          * @return Title
 137          */
 138         public function getTitle() {
 139                 return $this->title;
 140         }
 141
 142         /**
 143          * @return array
 144          */
 145         public function getParams() {
 146                 return $this->params;
 147         }
 148
 149         /**
 150          * @return int|null UNIX timestamp to delay running this job until, otherwise null
 151          */
 152         public function getReleaseTimestamp() {
 153                 return isset( $this->params['jobReleaseTimestamp'] )
 154                         ? wfTimestampOrNull( TS_UNIX, $this->params['jobReleaseTimestamp'] )
 155                         : null;
 156         }
 157
 158         /**
 159          * @return bool Whether only one of each identical set of jobs should be run
 160          */
 161         public function ignoreDuplicates() {
 162                 return !empty( $this->opts['removeDuplicates'] );
 163         }
 164
 165         /**
 166          * Subclasses may need to override this to make duplication detection work.
 167          * The resulting map conveys everything that makes the job unique. This is
 168          * only checked if ignoreDuplicates() returns true, meaning that duplicate
 169          * jobs are supposed to be ignored.
 170          *
 171          * @return array Map of key/values
 172          */
 173         public function getDeduplicationInfo() {
 174                 $info = array(
 175                         'type' => $this->getType(),
 176                         'namespace' => $this->getTitle()->getNamespace(),
 177                         'title' => $this->getTitle()->getDBkey(),
 178                         'params' => $this->getParams()
 179                 );
 180                 if ( is_array( $info['params'] ) ) {
 181                         // Identical jobs with different "root" jobs should count as duplicates
 182                         unset( $info['params']['rootJobSignature'] );
 183                         unset( $info['params']['rootJobTimestamp'] );
 184                         // Likewise for jobs with different delay times
 185                         unset( $info['params']['jobReleaseTimestamp'] );
 186                 }
 187
 188                 return $info;
 189         }
 190
 191         /**
 192          * @return array Field/value map that can immediately be serialized
 193          * @since 1.25
 194          */
 195         public function toSerializableArray() {
 196                 return array(
 197                         'type'   => $this->type,
 198                         'params' => $this->params,
 199                         'opts'   => $this->opts,
 200                         'title'  => array(
 201                                 'ns'  => $this->title->getNamespace(),
 202                                 'key' => $this->title->getDbKey()
 203                         )
 204                 );
 205         }
 206
 207         /**
 208          * @param array $map Field/value map
 209          * @return JobSpecification
 210          * @since 1.25
 211          */
 212         public static function newFromArray( array $map ) {
 213                 $title = Title::makeTitle( $map['title']['ns'], $map['title']['key'] );
 214
 215                 return new self( $map['type'], $map['params'], $map['opts'], $title );
 216         }
 217 }