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 * @see JobQueue::deduplicateRootJob()
66 public function getRootJobParams();
69 * @see JobQueue::deduplicateRootJob()
73 public function hasRootJobParams();
76 * @see JobQueue::deduplicateRootJob()
77 * @return bool Whether this is job is a root job
79 public function isRootJob();
82 * @return Title Descriptive title (this can simply be informative)
84 public function getTitle();
88 * Job queue task description base code
92 * $job = new JobSpecification(
94 * array( 'lives' => 1, 'usleep' => 100, 'pi' => 3.141569 ),
95 * array( 'removeDuplicates' => 1 ),
96 * Title::makeTitle( NS_SPECIAL, 'nullity' )
98 * JobQueueGroup::singleton()->push( $job )
104 class JobSpecification
implements IJobSpecification
{
108 /** @var array Array of job parameters or false if none */
118 * @param string $type
119 * @param array $params Map of key/values
120 * @param array $opts Map of key/values; includes 'removeDuplicates'
121 * @param Title $title Optional descriptive title
123 public function __construct(
124 $type, array $params, array $opts = [], Title
$title = null
126 $this->validateParams( $params );
127 $this->validateParams( $opts );
130 $this->params
= $params;
131 $this->title
= $title ?
: Title
::makeTitle( NS_SPECIAL
, 'Badtitle/' . get_class( $this ) );
136 * @param array $params
138 protected function validateParams( array $params ) {
139 foreach ( $params as $p => $v ) {
140 if ( is_array( $v ) ) {
141 $this->validateParams( $v );
142 } elseif ( !is_scalar( $v ) && $v !== null ) {
143 throw new UnexpectedValueException( "Job parameter $p is not JSON serializable." );
148 public function getType() {
152 public function getTitle() {
156 public function getParams() {
157 return $this->params
;
160 public function getReleaseTimestamp() {
161 return isset( $this->params
['jobReleaseTimestamp'] )
162 ?
wfTimestampOrNull( TS_UNIX
, $this->params
['jobReleaseTimestamp'] )
166 public function ignoreDuplicates() {
167 return !empty( $this->opts
['removeDuplicates'] );
170 public function getDeduplicationInfo() {
172 'type' => $this->getType(),
173 'namespace' => $this->getTitle()->getNamespace(),
174 'title' => $this->getTitle()->getDBkey(),
175 'params' => $this->getParams()
177 if ( is_array( $info['params'] ) ) {
178 // Identical jobs with different "root" jobs should count as duplicates
179 unset( $info['params']['rootJobSignature'] );
180 unset( $info['params']['rootJobTimestamp'] );
181 // Likewise for jobs with different delay times
182 unset( $info['params']['jobReleaseTimestamp'] );
188 public function getRootJobParams() {
190 'rootJobSignature' => isset( $this->params
['rootJobSignature'] )
191 ?
$this->params
['rootJobSignature']
193 'rootJobTimestamp' => isset( $this->params
['rootJobTimestamp'] )
194 ?
$this->params
['rootJobTimestamp']
199 public function hasRootJobParams() {
200 return isset( $this->params
['rootJobSignature'] )
201 && isset( $this->params
['rootJobTimestamp'] );
204 public function isRootJob() {
205 return $this->hasRootJobParams() && !empty( $this->params
['rootJobIsSelf'] );
209 * @return array Field/value map that can immediately be serialized
212 public function toSerializableArray() {
214 'type' => $this->type
,
215 'params' => $this->params
,
216 'opts' => $this->opts
,
218 'ns' => $this->title
->getNamespace(),
219 'key' => $this->title
->getDbKey()
225 * @param array $map Field/value map
226 * @return JobSpecification
229 public static function newFromArray( array $map ) {
230 $title = Title
::makeTitle( $map['title']['ns'], $map['title']['key'] );
232 return new self( $map['type'], $map['params'], $map['opts'], $title );