3 * Job queue task description base code.
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.
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.
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
24 * Job queue task description interface
29 interface IJobSpecification
{
31 * @return string Job type
33 public function getType();
38 public function getParams();
41 * @return int|null UNIX timestamp to delay running this job until, otherwise null
43 public function getReleaseTimestamp();
46 * @return bool Whether only one of each identical set of jobs should be run
48 public function ignoreDuplicates();
51 * Subclasses may need to override this to make duplication detection work.
52 * The resulting map conveys everything that makes the job unique. This is
53 * only checked if ignoreDuplicates() returns true, meaning that duplicate
54 * jobs are supposed to be ignored.
56 * @return array Map of key/values
58 public function getDeduplicationInfo();
61 * @see JobQueue::deduplicateRootJob()
65 public function getRootJobParams();
68 * @see JobQueue::deduplicateRootJob()
72 public function hasRootJobParams();
75 * @see JobQueue::deduplicateRootJob()
76 * @return bool Whether this is job is a root job
78 public function isRootJob();
81 * @return Title Descriptive title (this can simply be informative)
83 public function getTitle();
87 * Job queue task description base code
91 * $job = new JobSpecification(
93 * array( 'lives' => 1, 'usleep' => 100, 'pi' => 3.141569 ),
94 * array( 'removeDuplicates' => 1 ),
95 * Title::makeTitle( NS_SPECIAL, 'nullity' )
97 * JobQueueGroup::singleton()->push( $job )
103 class JobSpecification
implements IJobSpecification
{
107 /** @var array Array of job parameters or false if none */
117 * @param string $type
118 * @param array $params Map of key/values
119 * @param array $opts Map of key/values; includes 'removeDuplicates'
120 * @param Title $title Optional descriptive title
122 public function __construct(
123 $type, array $params, array $opts = [], Title
$title = null
125 $this->validateParams( $params );
126 $this->validateParams( $opts );
129 $this->params
= $params;
130 $this->title
= $title ?
: Title
::makeTitle( NS_SPECIAL
, 'Badtitle/' . static::class );
135 * @param array $params
137 protected function validateParams( array $params ) {
138 foreach ( $params as $p => $v ) {
139 if ( is_array( $v ) ) {
140 $this->validateParams( $v );
141 } elseif ( !is_scalar( $v ) && $v !== null ) {
142 throw new UnexpectedValueException( "Job parameter $p is not JSON serializable." );
147 public function getType() {
151 public function getTitle() {
155 public function getParams() {
156 return $this->params
;
159 public function getReleaseTimestamp() {
160 return isset( $this->params
['jobReleaseTimestamp'] )
161 ?
wfTimestampOrNull( TS_UNIX
, $this->params
['jobReleaseTimestamp'] )
165 public function ignoreDuplicates() {
166 return !empty( $this->opts
['removeDuplicates'] );
169 public function getDeduplicationInfo() {
171 'type' => $this->getType(),
172 'namespace' => $this->getTitle()->getNamespace(),
173 'title' => $this->getTitle()->getDBkey(),
174 'params' => $this->getParams()
176 if ( is_array( $info['params'] ) ) {
177 // Identical jobs with different "root" jobs should count as duplicates
178 unset( $info['params']['rootJobSignature'] );
179 unset( $info['params']['rootJobTimestamp'] );
180 // Likewise for jobs with different delay times
181 unset( $info['params']['jobReleaseTimestamp'] );
187 public function getRootJobParams() {
189 'rootJobSignature' => isset( $this->params
['rootJobSignature'] )
190 ?
$this->params
['rootJobSignature']
192 'rootJobTimestamp' => isset( $this->params
['rootJobTimestamp'] )
193 ?
$this->params
['rootJobTimestamp']
198 public function hasRootJobParams() {
199 return isset( $this->params
['rootJobSignature'] )
200 && isset( $this->params
['rootJobTimestamp'] );
203 public function isRootJob() {
204 return $this->hasRootJobParams() && !empty( $this->params
['rootJobIsSelf'] );
208 * @return array Field/value map that can immediately be serialized
211 public function toSerializableArray() {
213 'type' => $this->type
,
214 'params' => $this->params
,
215 'opts' => $this->opts
,
217 'ns' => $this->title
->getNamespace(),
218 'key' => $this->title
->getDBkey()
224 * @param array $map Field/value map
225 * @return JobSpecification
228 public static function newFromArray( array $map ) {
229 $title = Title
::makeTitle( $map['title']['ns'], $map['title']['key'] );
231 return new self( $map['type'], $map['params'], $map['opts'], $title );