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  */
  22
  23 /**
  24  * Job queue task description base code
  25  *
  26  * Example usage:
  27  * @code
  28  * $job = new JobSpecification(
  29  *              'null',
  30  *              [ 'lives' => 1, 'usleep' => 100, 'pi' => 3.141569 ],
  31  *              [ 'removeDuplicates' => 1 ]
  32  * );
  33  * JobQueueGroup::singleton()->push( $job )
  34  * @endcode
  35  *
  36  * @ingroup JobQueue
  37  * @since 1.23
  38  */
  39 class JobSpecification implements IJobSpecification {
  40         /** @var string */
  41         protected $type;
  42
  43         /** @var array Array of job parameters or false if none */
  44         protected $params;
  45
  46         /** @var Title */
  47         protected $title;
  48
  49         /** @var array */
  50         protected $opts;
  51
  52         /**
  53          * @param string $type
  54          * @param array $params Map of key/values
  55          * @param array $opts Map of key/values; includes 'removeDuplicates'
  56          * @param Title|null $title Optional descriptive title
  57          */
  58         public function __construct(
  59                 $type, array $params, array $opts = [], Title $title = null
  60         ) {
  61                 $this->validateParams( $params );
  62                 $this->validateParams( $opts );
  63
  64                 $this->type = $type;
  65                 if ( $title instanceof Title ) {
  66                         // Make sure JobQueue classes can pull the title from parameters alone
  67                         if ( $title->getDBkey() !== '' ) {
  68                                 $params += [
  69                                         'namespace' => $title->getNamespace(),
  70                                         'title' => $title->getDBkey()
  71                                 ];
  72                         }
  73                 } else {
  74                         $title = Title::makeTitle( NS_SPECIAL, '' );
  75                 }
  76                 $this->params = $params;
  77                 $this->title = $title;
  78                 $this->opts = $opts;
  79         }
  80
  81         /**
  82          * @param array $params
  83          */
  84         protected function validateParams( array $params ) {
  85                 foreach ( $params as $p => $v ) {
  86                         if ( is_array( $v ) ) {
  87                                 $this->validateParams( $v );
  88                         } elseif ( !is_scalar( $v ) && $v !== null ) {
  89                                 throw new UnexpectedValueException( "Job parameter $p is not JSON serializable." );
  90                         }
  91                 }
  92         }
  93
  94         public function getType() {
  95                 return $this->type;
  96         }
  97
  98         public function getTitle() {
  99                 return $this->title;
 100         }
 101
 102         public function getParams() {
 103                 return $this->params;
 104         }
 105
 106         public function getReleaseTimestamp() {
 107                 return isset( $this->params['jobReleaseTimestamp'] )
 108                         ? wfTimestampOrNull( TS_UNIX, $this->params['jobReleaseTimestamp'] )
 109                         : null;
 110         }
 111
 112         public function ignoreDuplicates() {
 113                 return !empty( $this->opts['removeDuplicates'] );
 114         }
 115
 116         public function getDeduplicationInfo() {
 117                 $info = [
 118                         'type' => $this->getType(),
 119                         'namespace' => $this->getTitle()->getNamespace(),
 120                         'title' => $this->getTitle()->getDBkey(),
 121                         'params' => $this->getParams()
 122                 ];
 123                 if ( is_array( $info['params'] ) ) {
 124                         // Identical jobs with different "root" jobs should count as duplicates
 125                         unset( $info['params']['rootJobSignature'] );
 126                         unset( $info['params']['rootJobTimestamp'] );
 127                         // Likewise for jobs with different delay times
 128                         unset( $info['params']['jobReleaseTimestamp'] );
 129                 }
 130
 131                 return $info;
 132         }
 133
 134         public function getRootJobParams() {
 135                 return [
 136                         'rootJobSignature' => $this->params['rootJobSignature'] ?? null,
 137                         'rootJobTimestamp' => $this->params['rootJobTimestamp'] ?? null
 138                 ];
 139         }
 140
 141         public function hasRootJobParams() {
 142                 return isset( $this->params['rootJobSignature'] )
 143                         && isset( $this->params['rootJobTimestamp'] );
 144         }
 145
 146         public function isRootJob() {
 147                 return $this->hasRootJobParams() && !empty( $this->params['rootJobIsSelf'] );
 148         }
 149
 150         /**
 151          * @return array Field/value map that can immediately be serialized
 152          * @since 1.25
 153          */
 154         public function toSerializableArray() {
 155                 return [
 156                         'type'   => $this->type,
 157                         'params' => $this->params,
 158                         'opts'   => $this->opts,
 159                         'title'  => [
 160                                 'ns'  => $this->title->getNamespace(),
 161                                 'key' => $this->title->getDBkey()
 162                         ]
 163                 ];
 164         }
 165
 166         /**
 167          * @param array $map Field/value map
 168          * @return JobSpecification
 169          * @since 1.25
 170          */
 171         public static function newFromArray( array $map ) {
 172                 $title = Title::makeTitle( $map['title']['ns'], $map['title']['key'] );
 173
 174                 return new self( $map['type'], $map['params'], $map['opts'], $title );
 175         }
 176 }