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