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 * @return Title Descriptive title (this can simply be informative)
78 public function getTitle();
82 * Job queue task description base code
86 * $job = new JobSpecification(
88 * array( 'lives' => 1, 'usleep' => 100, 'pi' => 3.141569 ),
89 * array( 'removeDuplicates' => 1 ),
90 * Title::makeTitle( NS_SPECIAL, 'nullity' )
92 * JobQueueGroup::singleton()->push( $job )
98 class JobSpecification
implements IJobSpecification
{
102 /** @var array Array of job parameters or false if none */
112 * @param string $type
113 * @param array $params Map of key/values
114 * @param array $opts Map of key/values; includes 'removeDuplicates'
115 * @param Title $title Optional descriptive title
117 public function __construct(
118 $type, array $params, array $opts = array(), Title
$title = null
120 $this->validateParams( $params );
121 $this->validateParams( $opts );
124 $this->params
= $params;
125 $this->title
= $title ?
: Title
::makeTitle( NS_SPECIAL
, 'Badtitle/' . get_class( $this ) );
130 * @param array $params
132 protected function validateParams( array $params ) {
133 foreach ( $params as $p => $v ) {
134 if ( is_array( $v ) ) {
135 $this->validateParams( $v );
136 } elseif ( !is_scalar( $v ) && $v !== null ) {
137 throw new UnexpectedValueException( "Job parameter $p is not JSON serializable." );
142 public function getType() {
146 public function getTitle() {
150 public function getParams() {
151 return $this->params
;
154 public function getReleaseTimestamp() {
155 return isset( $this->params
['jobReleaseTimestamp'] )
156 ?
wfTimestampOrNull( TS_UNIX
, $this->params
['jobReleaseTimestamp'] )
160 public function ignoreDuplicates() {
161 return !empty( $this->opts
['removeDuplicates'] );
164 public function getDeduplicationInfo() {
166 'type' => $this->getType(),
167 'namespace' => $this->getTitle()->getNamespace(),
168 'title' => $this->getTitle()->getDBkey(),
169 'params' => $this->getParams()
171 if ( is_array( $info['params'] ) ) {
172 // Identical jobs with different "root" jobs should count as duplicates
173 unset( $info['params']['rootJobSignature'] );
174 unset( $info['params']['rootJobTimestamp'] );
175 // Likewise for jobs with different delay times
176 unset( $info['params']['jobReleaseTimestamp'] );
182 public function getRootJobParams() {
184 'rootJobSignature' => isset( $this->params
['rootJobSignature'] )
185 ?
$this->params
['rootJobSignature']
187 'rootJobTimestamp' => isset( $this->params
['rootJobTimestamp'] )
188 ?
$this->params
['rootJobTimestamp']
193 public function hasRootJobParams() {
194 return isset( $this->params
['rootJobSignature'] )
195 && isset( $this->params
['rootJobTimestamp'] );
199 * @return array Field/value map that can immediately be serialized
202 public function toSerializableArray() {
204 'type' => $this->type
,
205 'params' => $this->params
,
206 'opts' => $this->opts
,
208 'ns' => $this->title
->getNamespace(),
209 'key' => $this->title
->getDbKey()
215 * @param array $map Field/value map
216 * @return JobSpecification
219 public static function newFromArray( array $map ) {
220 $title = Title
::makeTitle( $map['title']['ns'], $map['title']['key'] );
222 return new self( $map['type'], $map['params'], $map['opts'], $title );