*/
private $mPageSet;
- private $params;
- private $iwUrl;
+ private $mParams;
private $mNamedDB = array();
private $mModuleMgr;
+ private $mGeneratorContinue;
+ private $mUseLegacyContinue;
/**
* @param $main ApiMain
* If no such connection has been requested before, it will be created.
* Subsequent calls with the same $name will return the same connection
* as the first, regardless of the values of $db and $groups
- * @param $name string Name to assign to the database connection
- * @param $db int One of the DB_* constants
- * @param $groups array Query groups
+ * @param string $name Name to assign to the database connection
+ * @param int $db One of the DB_* constants
+ * @param array $groups Query groups
* @return DatabaseBase
*/
public function getNamedDB( $name, $db, $groups ) {
/**
* Get whether the specified module is a prop, list or a meta query module
* @deprecated since 1.21, use getModuleManager()->getModuleGroup()
- * @param $moduleName string Name of the module to find type for
+ * @param string $moduleName Name of the module to find type for
* @return mixed string or null
*/
function getModuleType( $moduleName ) {
* #5 Execute all requested modules
*/
public function execute() {
- $this->params = $this->extractRequestParams();
- $this->iwUrl = $this->params['iwurl'];
+ $this->mParams = $this->extractRequestParams();
- // Instantiate requested modules
- $modules = array();
- $this->instantiateModules( $modules, 'prop' );
- $this->instantiateModules( $modules, 'list' );
- $this->instantiateModules( $modules, 'meta' );
-
- // Query modules may optimize data requests through the $this->getPageSet()
- // object by adding extra fields from the page table.
- // This function will gather all the extra request fields from the modules.
- foreach ( $modules as $module ) {
- if ( !$this->getRequest()->wasPosted() && $module->mustBePosted() ) {
- $this->dieUsageMsgOrDebug( array( 'mustbeposted', $module->getModuleName() ) );
- }
+ // $pagesetParams is a array of parameter names used by the pageset generator
+ // or null if pageset has already finished and is no longer needed
+ // $completeModules is a set of complete modules with the name as key
+ $this->initContinue( $pagesetParams, $completeModules );
- $module->requestExtraData( $this->mPageSet );
+ // Instantiate requested modules
+ $allModules = array();
+ $this->instantiateModules( $allModules, 'prop' );
+ $propModules = $allModules; // Keep a copy
+ $this->instantiateModules( $allModules, 'list' );
+ $this->instantiateModules( $allModules, 'meta' );
+
+ // Filter modules based on continue parameter
+ $modules = $this->initModules( $allModules, $completeModules, $pagesetParams !== null );
+
+ // Execute pageset if in legacy mode or if pageset is not done
+ if ( $completeModules === null || $pagesetParams !== null ) {
+ // Populate page/revision information
+ $this->mPageSet->execute();
+ // Record page information (title, namespace, if exists, etc)
+ $this->outputGeneralPageInfo();
+ } else {
+ $this->mPageSet->executeDryRun();
}
- // Populate page/revision information
- $this->mPageSet->execute();
$cacheMode = $this->mPageSet->getCacheMode();
- // Record page information (title, namespace, if exists, etc)
- $this->outputGeneralPageInfo();
-
- // Execute all requested modules.
- /**
- * @var $module ApiQueryBase
- */
+ // Execute all unfinished modules
+ /** @var $module ApiQueryBase */
foreach ( $modules as $module ) {
$params = $module->extractRequestParams();
$cacheMode = $this->mergeCacheMode(
// Set the cache mode
$this->getMain()->setCacheMode( $cacheMode );
+
+ if ( $completeModules === null ) {
+ return; // Legacy continue, we are done
+ }
+
+ // Reformat query-continue result section
+ $result = $this->getResult();
+ $qc = $result->getData();
+ if ( isset( $qc['query-continue'] ) ) {
+ $qc = $qc['query-continue'];
+ $result->unsetValue( null, 'query-continue' );
+ } elseif ( $this->mGeneratorContinue !== null ) {
+ $qc = array();
+ } else {
+ // no more "continue"s, we are done!
+ return;
+ }
+
+ // we are done with all the modules that do not have result in query-continue
+ $completeModules = array_merge( $completeModules, array_diff_key( $modules, $qc ) );
+ if ( $pagesetParams !== null ) {
+ // The pageset is still in use, check if all props have finished
+ $incompleteProps = array_intersect_key( $propModules, $qc );
+ if ( count( $incompleteProps ) > 0 ) {
+ // Properties are not done, continue with the same pageset state - copy current parameters
+ $main = $this->getMain();
+ $contValues = array();
+ foreach ( $pagesetParams as $param ) {
+ // The param name is already prefix-encoded
+ $contValues[$param] = $main->getVal( $param );
+ }
+ } elseif ( $this->mGeneratorContinue !== null ) {
+ // Move to the next set of pages produced by pageset, properties need to be restarted
+ $contValues = $this->mGeneratorContinue;
+ $pagesetParams = array_keys( $contValues );
+ $completeModules = array_diff_key( $completeModules, $propModules );
+ } else {
+ // Done with the pageset, finish up with the the lists and meta modules
+ $pagesetParams = null;
+ }
+ }
+
+ $continue = '||' . implode( '|', array_keys( $completeModules ) );
+ if ( $pagesetParams !== null ) {
+ // list of all pageset parameters to use in the next request
+ $continue = implode( '|', $pagesetParams ) . $continue;
+ } else {
+ // we are done with the pageset
+ $contValues = array();
+ $continue = '-' . $continue;
+ }
+ $contValues['continue'] = $continue;
+ foreach ( $qc as $qcModule ) {
+ foreach ( $qcModule as $qcKey => $qcValue ) {
+ $contValues[$qcKey] = $qcValue;
+ }
+ }
+ $this->getResult()->addValue( null, 'continue', $contValues );
+ }
+
+ /**
+ * Parse 'continue' parameter into the list of complete modules and a list of generator parameters
+ * @param array|null $pagesetParams returns list of generator params or null if pageset is done
+ * @param array|null $completeModules returns list of finished modules (as keys), or null if legacy
+ */
+ private function initContinue( &$pagesetParams, &$completeModules ) {
+ $pagesetParams = array();
+ $continue = $this->mParams['continue'];
+ if ( $continue !== null ) {
+ $this->mUseLegacyContinue = false;
+ if ( $continue !== '' ) {
+ // Format: ' pagesetParam1 | pagesetParam2 || module1 | module2 | module3 | ...
+ // If pageset is done, use '-'
+ $continue = explode( '||', $continue );
+ $this->dieContinueUsageIf( count( $continue ) !== 2 );
+ if ( $continue[0] === '-' ) {
+ $pagesetParams = null; // No need to execute pageset
+ } elseif ( $continue[0] !== '' ) {
+ // list of pageset params that might need to be repeated
+ $pagesetParams = explode( '|', $continue[0] );
+ }
+ $continue = $continue[1];
+ }
+ if ( $continue !== '' ) {
+ $completeModules = array_flip( explode( '|', $continue ) );
+ } else {
+ $completeModules = array();
+ }
+ } else {
+ $this->mUseLegacyContinue = true;
+ $completeModules = null;
+ }
+ }
+
+ /**
+ * Validate sub-modules, filter out completed ones, and do requestExtraData()
+ * @param array $allModules An dict of name=>instance of all modules requested by the client
+ * @param array|null $completeModules list of finished modules, or null if legacy continue
+ * @param bool $usePageset True if pageset will be executed
+ * @return array of modules to be processed during this execution
+ */
+ private function initModules( $allModules, $completeModules, $usePageset ) {
+ $modules = $allModules;
+ $tmp = $completeModules;
+ $wasPosted = $this->getRequest()->wasPosted();
+
+ /** @var $module ApiQueryBase */
+ foreach ( $allModules as $moduleName => $module ) {
+ if ( !$wasPosted && $module->mustBePosted() ) {
+ $this->dieUsageMsgOrDebug( array( 'mustbeposted', $moduleName ) );
+ }
+ if ( $completeModules !== null && array_key_exists( $moduleName, $completeModules ) ) {
+ // If this module is done, mark all its params as used
+ $module->extractRequestParams();
+ // Make sure this module is not used during execution
+ unset( $modules[$moduleName] );
+ unset( $tmp[$moduleName] );
+ } elseif ( $completeModules === null || $usePageset ) {
+ // Query modules may optimize data requests through the $this->getPageSet()
+ // object by adding extra fields from the page table.
+ // This function will gather all the extra request fields from the modules.
+ $module->requestExtraData( $this->mPageSet );
+ } else {
+ // Error - this prop module must have finished before generator is done
+ $this->dieContinueUsageIf( $this->mModuleMgr->getModuleGroup( $moduleName ) === 'prop' );
+ }
+ }
+ $this->dieContinueUsageIf( $completeModules !== null && count( $tmp ) !== 0 );
+ return $modules;
}
/**
/**
* Create instances of all modules requested by the client
- * @param $modules Array to append instantiated modules to
- * @param $param string Parameter name to read modules from
+ * @param array $modules to append instantiated modules to
+ * @param string $param Parameter name to read modules from
*/
private function instantiateModules( &$modules, $param ) {
- if ( isset( $this->params[$param] ) ) {
- foreach ( $this->params[$param] as $moduleName ) {
- $modules[] = $this->mModuleMgr->getModule( $moduleName );
+ if ( isset( $this->mParams[$param] ) ) {
+ foreach ( $this->mParams[$param] as $moduleName ) {
+ $instance = $this->mModuleMgr->getModule( $moduleName, $param );
+ if ( $instance === null ) {
+ ApiBase::dieDebug( __METHOD__, 'Error instantiating module' );
+ }
+ // Ignore duplicates. TODO 2.0: die()?
+ if ( !array_key_exists( $moduleName, $modules ) ) {
+ $modules[$moduleName] = $instance;
+ }
}
}
}
if ( $values ) {
$result->addValue( 'query', 'converted', $values );
}
- $values = $pageSet->getInterwikiTitlesAsResult( $result, $this->iwUrl );
+ $values = $pageSet->getInterwikiTitlesAsResult( $result, $this->mParams['iwurl'] );
if ( $values ) {
$result->addValue( 'query', 'interwiki', $values );
}
);
}
// Report special pages
+ /** @var $title Title */
foreach ( $pageSet->getSpecialTitles() as $fakeId => $title ) {
$vals = array();
ApiQueryBase::addTitleInfo( $vals, $title );
$vals['special'] = '';
if ( $title->isSpecialPage() &&
- !SpecialPageFactory::exists( $title->getDbKey() ) ) {
+ !SpecialPageFactory::exists( $title->getDBkey() ) ) {
$vals['missing'] = '';
} elseif ( $title->getNamespace() == NS_MEDIA &&
!wfFindFile( $title ) ) {
}
if ( count( $pages ) ) {
- if ( $this->params['indexpageids'] ) {
+ if ( $this->mParams['indexpageids'] ) {
$pageIDs = array_keys( $pages );
// json treats all map keys as strings - converting to match
$pageIDs = array_map( 'strval', $pageIDs );
$result->setIndexedTagName( $pages, 'page' );
$result->addValue( 'query', 'pages', $pages );
}
- if ( $this->params['export'] ) {
+ if ( $this->mParams['export'] ) {
$this->doExport( $pageSet, $result );
}
}
+ /**
+ * This method is called by the generator base when generator in the smart-continue
+ * mode tries to set 'query-continue' value. ApiQuery stores those values separately
+ * until the post-processing when it is known if the generation should continue or repeat.
+ * @param ApiQueryGeneratorBase $module generator module
+ * @param string $paramName
+ * @param mixed $paramValue
+ * @return bool true if processed, false if this is a legacy continue
+ */
+ public function setGeneratorContinue( $module, $paramName, $paramValue ) {
+ if ( $this->mUseLegacyContinue ) {
+ return false;
+ }
+ $paramName = $module->encodeParamName( $paramName );
+ if ( $this->mGeneratorContinue === null ) {
+ $this->mGeneratorContinue = array();
+ }
+ $this->mGeneratorContinue[$paramName] = $paramValue;
+ return true;
+ }
+
/**
* @param $pageSet ApiPageSet Pages to be exported
* @param $result ApiResult Result to output to
$titles = $pageSet->getGoodTitles();
if ( count( $titles ) ) {
$user = $this->getUser();
+ /** @var $title Title */
foreach ( $titles as $title ) {
if ( $title->userCan( 'read', $user ) ) {
$exportTitles[] = $title;
// It's not continuable, so it would cause more
// problems than it'd solve
$result->disableSizeCheck();
- if ( $this->params['exportnowrap'] ) {
+ if ( $this->mParams['exportnowrap'] ) {
$result->reset();
// Raw formatter will handle this
$result->addValue( null, 'text', $exportxml );
'export' => false,
'exportnowrap' => false,
'iwurl' => false,
+ 'continue' => null,
);
if ( $flags ) {
$result += $this->getPageSet()->getFinalParams( $flags );
/**
* For all modules of a given group, generate help messages and join them together
- * @param $group string Module group
+ * @param string $group Module group
* @return string
*/
private function makeHelpMsgHelper( $group ) {
'export' => 'Export the current revisions of all given or generated pages',
'exportnowrap' => 'Return the export XML without wrapping it in an XML result (same format as Special:Export). Can only be used with export',
'iwurl' => 'Whether to get the full URL if the title is an interwiki link',
+ 'continue' => array(
+ 'When present, formats query-continue as key-value pairs that should simply be merged into the original request.',
+ 'This parameter must be set to an empty string in the initial query.',
+ 'This parameter is recommended for all new development, and will be made default in the next API version.' ),
);
}
public function getExamples() {
return array(
- 'api.php?action=query&prop=revisions&meta=siteinfo&titles=Main%20Page&rvprop=user|comment',
- 'api.php?action=query&generator=allpages&gapprefix=API/&prop=revisions',
+ 'api.php?action=query&prop=revisions&meta=siteinfo&titles=Main%20Page&rvprop=user|comment&continue=',
+ 'api.php?action=query&generator=allpages&gapprefix=API/&prop=revisions&continue=',
);
}