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
25 * Job queue task description interface
30 interface IJobSpecification
{
32 * @return string Job type
34 public function getType();
39 public function getParams();
42 * @return int|null UNIX timestamp to delay running this job until, otherwise null
44 public function getReleaseTimestamp();
47 * @return bool Whether only one of each identical set of jobs should be run
49 public function ignoreDuplicates();
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.
57 * @return array Map of key/values
59 public function getDeduplicationInfo();
62 * @return Title Descriptive title (this can simply be informative)
64 public function getTitle();
68 * Job queue task description base code
72 * $job = new JobSpecification(
74 * array( 'lives' => 1, 'usleep' => 100, 'pi' => 3.141569 ),
75 * array( 'removeDuplicates' => 1 ),
76 * Title::makeTitle( NS_SPECIAL, 'nullity' )
78 * JobQueueGroup::singleton()->push( $job )
84 class JobSpecification
implements IJobSpecification
{
88 /** @var array Array of job parameters or false if none */
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
103 public function __construct(
104 $type, array $params, array $opts = array(), Title
$title = null
106 $this->validateParams( $params );
107 $this->validateParams( $opts );
110 $this->params
= $params;
111 $this->title
= $title ?
: Title
::makeTitle( NS_SPECIAL
, 'Badtitle/' . get_class( $this ) );
116 * @param array $params
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." );
131 public function getType() {
138 public function getTitle() {
145 public function getParams() {
146 return $this->params
;
150 * @return int|null UNIX timestamp to delay running this job until, otherwise null
152 public function getReleaseTimestamp() {
153 return isset( $this->params
['jobReleaseTimestamp'] )
154 ?
wfTimestampOrNull( TS_UNIX
, $this->params
['jobReleaseTimestamp'] )
159 * @return bool Whether only one of each identical set of jobs should be run
161 public function ignoreDuplicates() {
162 return !empty( $this->opts
['removeDuplicates'] );
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.
171 * @return array Map of key/values
173 public function getDeduplicationInfo() {
175 'type' => $this->getType(),
176 'namespace' => $this->getTitle()->getNamespace(),
177 'title' => $this->getTitle()->getDBkey(),
178 'params' => $this->getParams()
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'] );
192 * @return array Field/value map that can immediately be serialized
195 public function toSerializableArray() {
197 'type' => $this->type
,
198 'params' => $this->params
,
199 'opts' => $this->opts
,
201 'ns' => $this->title
->getNamespace(),
202 'key' => $this->title
->getDbKey()
208 * @param array $map Field/value map
209 * @return JobSpecification
212 public static function newFromArray( array $map ) {
213 $title = Title
::makeTitle( $map['title']['ns'], $map['title']['key'] );
215 return new self( $map['type'], $map['params'], $map['opts'], $title );