3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
22 * This manages continuation state.
23 * @since 1.25 this is no longer a subclass of ApiBase
26 class ApiContinuationManager
{
29 private $allModules = array();
30 private $generatedModules = array();
32 private $continuationData = array();
33 private $generatorContinuationData = array();
35 private $generatorParams = array();
36 private $generatorDone = false;
39 * @param ApiBase $module Module starting the continuation
40 * @param ApiBase[] $allModules Contains ApiBase instances that will be executed
41 * @param array $generatedModules Names of modules that depend on the generator
43 public function __construct(
44 ApiBase
$module, array $allModules = array(), array $generatedModules = array()
46 $this->source
= get_class( $module );
47 $request = $module->getRequest();
49 $this->generatedModules
= $generatedModules
50 ?
array_combine( $generatedModules, $generatedModules )
54 $continue = $request->getVal( 'continue', '' );
55 if ( $continue !== '' ) {
56 $continue = explode( '||', $continue );
57 if ( count( $continue ) !== 2 ) {
58 throw new UsageException(
59 'Invalid continue param. You should pass the original value returned by the previous query',
63 $this->generatorDone
= ( $continue[0] === '-' );
64 $skip = explode( '|', $continue[1] );
65 if ( !$this->generatorDone
) {
66 $params = explode( '|', $continue[0] );
68 $this->generatorParams
= array_intersect_key(
69 $request->getValues(),
74 // When the generator is complete, don't run any modules that
76 $skip +
= $this->generatedModules
;
80 foreach ( $allModules as $module ) {
81 $name = $module->getModuleName();
82 if ( in_array( $name, $skip, true ) ) {
83 $this->allModules
[$name] = false;
84 // Prevent spurious "unused parameter" warnings
85 $module->extractRequestParams();
87 $this->allModules
[$name] = $module;
93 * Get the class that created this manager
96 public function getSource() {
101 * Is the generator done?
104 public function isGeneratorDone() {
105 return $this->generatorDone
;
109 * Get the list of modules that should actually be run
112 public function getRunModules() {
113 return array_values( array_filter( $this->allModules
) );
117 * Set the continuation parameter for a module
118 * @param ApiBase $module
119 * @param string $paramName
120 * @param string|array $paramValue
121 * @throws UnexpectedValueException
123 public function addContinueParam( ApiBase
$module, $paramName, $paramValue ) {
124 $name = $module->getModuleName();
125 if ( !isset( $this->allModules
[$name] ) ) {
126 throw new UnexpectedValueException(
127 "Module '$name' called " . __METHOD__
.
128 ' but was not passed to ' . __CLASS__
. '::__construct'
131 if ( !$this->allModules
[$name] ) {
132 throw new UnexpectedValueException(
133 "Module '$name' was not supposed to have been executed, but " .
134 'it was executed anyway'
137 $paramName = $module->encodeParamName( $paramName );
138 if ( is_array( $paramValue ) ) {
139 $paramValue = join( '|', $paramValue );
141 $this->continuationData
[$name][$paramName] = $paramValue;
145 * Set the continuation parameter for the generator module
146 * @param ApiBase $module
147 * @param string $paramName
148 * @param string|array $paramValue
150 public function addGeneratorContinueParam( ApiBase
$module, $paramName, $paramValue ) {
151 $name = $module->getModuleName();
152 $paramName = $module->encodeParamName( $paramName );
153 if ( is_array( $paramValue ) ) {
154 $paramValue = join( '|', $paramValue );
156 $this->generatorContinuationData
[$name][$paramName] = $paramValue;
160 * Fetch raw continuation data
163 public function getRawContinuation() {
164 return array_merge_recursive( $this->continuationData
, $this->generatorContinuationData
);
168 * Fetch continuation result data
169 * @return array Array( (array)$data, (bool)$batchcomplete )
171 public function getContinuation() {
173 $batchcomplete = false;
175 $finishedModules = array_diff(
176 array_keys( $this->allModules
),
177 array_keys( $this->continuationData
)
180 // First, grab the non-generator-using continuation data
181 $continuationData = array_diff_key( $this->continuationData
, $this->generatedModules
);
182 foreach ( $continuationData as $module => $kvp ) {
186 // Next, handle the generator-using continuation data
187 $continuationData = array_intersect_key( $this->continuationData
, $this->generatedModules
);
188 if ( $continuationData ) {
189 // Some modules are unfinished: include those params, and copy
190 // the generator params.
191 foreach ( $continuationData as $module => $kvp ) {
194 $data +
= $this->generatorParams
;
195 $generatorKeys = join( '|', array_keys( $this->generatorParams
) );
196 } elseif ( $this->generatorContinuationData
) {
197 // All the generator-using modules are complete, but the
198 // generator isn't. Continue the generator and restart the
199 // generator-using modules
200 $generatorParams = array();
201 foreach ( $this->generatorContinuationData
as $kvp ) {
202 $generatorParams +
= $kvp;
204 $data +
= $generatorParams;
205 $finishedModules = array_diff( $finishedModules, $this->generatedModules
);
206 $generatorKeys = join( '|', array_keys( $generatorParams ) );
207 $batchcomplete = true;
209 // Generator and prop modules are all done. Mark it so.
210 $generatorKeys = '-';
211 $batchcomplete = true;
214 // Set 'continue' if any continuation data is set or if the generator
215 // still needs to run
216 if ( $data ||
$generatorKeys !== '-' ) {
217 $data['continue'] = $generatorKeys . '||' . join( '|', $finishedModules );
220 return array( $data, $batchcomplete );
224 * Store the continuation data into the result
225 * @param ApiResult $result
227 public function setContinuationIntoResult( ApiResult
$result ) {
228 list( $data, $batchcomplete ) = $this->getContinuation();
230 $result->addValue( null, 'continue', $data,
231 ApiResult
::ADD_ON_TOP | ApiResult
::NO_SIZE_CHECK
);
233 if ( $batchcomplete ) {
234 $result->addValue( null, 'batchcomplete', true,
235 ApiResult
::ADD_ON_TOP | ApiResult
::NO_SIZE_CHECK
);