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          * @see JobQueue::deduplicateRootJob()
  63          * @return array
  64          * @since 1.26
  65          */
  66         public function getRootJobParams();
  67
  68         /**
  69          * @see JobQueue::deduplicateRootJob()
  70          * @return bool
  71          * @since 1.22
  72          */
  73         public function hasRootJobParams();
  74
  75         /**
  76          * @return Title Descriptive title (this can simply be informative)
  77          */
  78         public function getTitle();
  79 }
  80
  81 /**
  82  * Job queue task description base code
  83  *
  84  * Example usage:
  85  * @code
  86  * $job = new JobSpecification(
  87  *              'null',
  88  *              array( 'lives' => 1, 'usleep' => 100, 'pi' => 3.141569 ),
  89  *              array( 'removeDuplicates' => 1 ),
  90  *              Title::makeTitle( NS_SPECIAL, 'nullity' )
  91  * );
  92  * JobQueueGroup::singleton()->push( $job )
  93  * @endcode
  94  *
  95  * @ingroup JobQueue
  96  * @since 1.23
  97  */
  98 class JobSpecification implements IJobSpecification {
  99         /** @var string */
 100         protected $type;
 101
 102         /** @var array Array of job parameters or false if none */
 103         protected $params;
 104
 105         /** @var Title */
 106         protected $title;
 107
 108         /** @var array */
 109         protected $opts;
 110
 111         /**
 112          * @param string $type
 113          * @param array $params Map of key/values
 114          * @param array $opts Map of key/values; includes 'removeDuplicates'
 115          * @param Title $title Optional descriptive title
 116          */
 117         public function __construct(
 118                 $type, array $params, array $opts = array(), Title $title = null
 119         ) {
 120                 $this->validateParams( $params );
 121                 $this->validateParams( $opts );
 122
 123                 $this->type = $type;
 124                 $this->params = $params;
 125                 $this->title = $title ?: Title::makeTitle( NS_SPECIAL, 'Badtitle/' . get_class( $this ) );
 126                 $this->opts = $opts;
 127         }
 128
 129         /**
 130          * @param array $params
 131          */
 132         protected function validateParams( array $params ) {
 133                 foreach ( $params as $p => $v ) {
 134                         if ( is_array( $v ) ) {
 135                                 $this->validateParams( $v );
 136                         } elseif ( !is_scalar( $v ) && $v !== null ) {
 137                                 throw new UnexpectedValueException( "Job parameter $p is not JSON serializable." );
 138                         }
 139                 }
 140         }
 141
 142         public function getType() {
 143                 return $this->type;
 144         }
 145
 146         public function getTitle() {
 147                 return $this->title;
 148         }
 149
 150         public function getParams() {
 151                 return $this->params;
 152         }
 153
 154         public function getReleaseTimestamp() {
 155                 return isset( $this->params['jobReleaseTimestamp'] )
 156                         ? wfTimestampOrNull( TS_UNIX, $this->params['jobReleaseTimestamp'] )
 157                         : null;
 158         }
 159
 160         public function ignoreDuplicates() {
 161                 return !empty( $this->opts['removeDuplicates'] );
 162         }
 163
 164         public function getDeduplicationInfo() {
 165                 $info = array(
 166                         'type' => $this->getType(),
 167                         'namespace' => $this->getTitle()->getNamespace(),
 168                         'title' => $this->getTitle()->getDBkey(),
 169                         'params' => $this->getParams()
 170                 );
 171                 if ( is_array( $info['params'] ) ) {
 172                         // Identical jobs with different "root" jobs should count as duplicates
 173                         unset( $info['params']['rootJobSignature'] );
 174                         unset( $info['params']['rootJobTimestamp'] );
 175                         // Likewise for jobs with different delay times
 176                         unset( $info['params']['jobReleaseTimestamp'] );
 177                 }
 178
 179                 return $info;
 180         }
 181
 182         public function getRootJobParams() {
 183                 return array(
 184                         'rootJobSignature' => isset( $this->params['rootJobSignature'] )
 185                                 ? $this->params['rootJobSignature']
 186                                 : null,
 187                         'rootJobTimestamp' => isset( $this->params['rootJobTimestamp'] )
 188                                 ? $this->params['rootJobTimestamp']
 189                                 : null
 190                 );
 191         }
 192
 193         public function hasRootJobParams() {
 194                 return isset( $this->params['rootJobSignature'] )
 195                         && isset( $this->params['rootJobTimestamp'] );
 196         }
 197
 198         /**
 199          * @return array Field/value map that can immediately be serialized
 200          * @since 1.25
 201          */
 202         public function toSerializableArray() {
 203                 return array(
 204                         'type'   => $this->type,
 205                         'params' => $this->params,
 206                         'opts'   => $this->opts,
 207                         'title'  => array(
 208                                 'ns'  => $this->title->getNamespace(),
 209                                 'key' => $this->title->getDbKey()
 210                         )
 211                 );
 212         }
 213
 214         /**
 215          * @param array $map Field/value map
 216          * @return JobSpecification
 217          * @since 1.25
 218          */
 219         public static function newFromArray( array $map ) {
 220                 $title = Title::makeTitle( $map['title']['ns'], $map['title']['key'] );
 221
 222                 return new self( $map['type'], $map['params'], $map['opts'], $title );
 223         }
 224 }