From: Aaron Schulz <aschulz@wikimedia.org>
Date: Thu, 30 Nov 2017 22:03:38 +0000 (-0800)
Subject: Add missing @throw tags to IDatabase/Database
X-Git-Tag: 1.31.0-rc.0~1340^2
X-Git-Url: http://git.cyclocoop.org/%24image?a=commitdiff_plain;h=8503692309824773931bd4966b3ebea24fcede1d;p=lhc%2Fweb%2Fwiklou.git

Add missing @throw tags to IDatabase/Database

Change-Id: I235c5beacce38e9121fb1db94ce410d010356fcf
---

diff --git a/includes/libs/rdbms/database/Database.php b/includes/libs/rdbms/database/Database.php
index e04566eb49..9875d93e55 100644
--- a/includes/libs/rdbms/database/Database.php
+++ b/includes/libs/rdbms/database/Database.php
@@ -3273,14 +3273,15 @@ abstract class Database implements IDatabase, IMaintainableDatabase, LoggerAware
 	 * @see WANObjectCache::getWithSetCallback()
 	 *
 	 * @param IDatabase $db1
-	 * @param IDatabase $dbs,...
+	 * @param IDatabase $db2 [optional]
 	 * @return array Map of values:
 	 *   - lag: highest lag of any of the DBs or false on error (e.g. replication stopped)
 	 *   - since: oldest UNIX timestamp of any of the DB lag estimates
 	 *   - pending: whether any of the DBs have uncommitted changes
+	 * @throws DBError
 	 * @since 1.27
 	 */
-	public static function getCacheSetOptions( IDatabase $db1 ) {
+	public static function getCacheSetOptions( IDatabase $db1, IDatabase $db2 = null ) {
 		$res = [ 'lag' => 0, 'since' => INF, 'pending' => false ];
 		foreach ( func_get_args() as $db ) {
 			/** @var IDatabase $db */
diff --git a/includes/libs/rdbms/database/IDatabase.php b/includes/libs/rdbms/database/IDatabase.php
index bbf88dc8b5..6047fb033d 100644
--- a/includes/libs/rdbms/database/IDatabase.php
+++ b/includes/libs/rdbms/database/IDatabase.php
@@ -26,7 +26,6 @@
 namespace Wikimedia\Rdbms;
 
 use Wikimedia\ScopedCallback;
-use Exception;
 use RuntimeException;
 use UnexpectedValueException;
 use stdClass;
@@ -525,9 +524,9 @@ interface IDatabase {
 	 *     comment (you can use __METHOD__ or add some extra info)
 	 * @param bool $tempIgnore Whether to avoid throwing an exception on errors...
 	 *     maybe best to catch the exception instead?
-	 * @throws DBError
 	 * @return bool|IResultWrapper True for a successful write query, IResultWrapper object
 	 *     for a successful read query, or false on failure if $tempIgnore set
+	 * @throws DBError
 	 */
 	public function query( $sql, $fname = __METHOD__, $tempIgnore = false );
 
@@ -570,7 +569,7 @@ interface IDatabase {
 	 * @param string|array $join_conds The query join conditions. See IDatabase::select() for details.
 	 *
 	 * @return mixed The value from the field
-	 * @throws DBQueryError
+	 * @throws DBError
 	 */
 	public function selectField(
 		$table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
@@ -593,7 +592,7 @@ interface IDatabase {
 	 * @param string|array $join_conds The query join conditions. See IDatabase::select() for details.
 	 *
 	 * @return array The values from the field
-	 * @throws DBQueryError
+	 * @throws DBError
 	 * @since 1.25
 	 */
 	public function selectFieldValues(
@@ -758,7 +757,7 @@ interface IDatabase {
 	 *    [ 'page' => [ 'LEFT JOIN', 'page_latest=rev_id' ] ]
 	 *
 	 * @return IResultWrapper Resulting rows
-	 * @throws DBQueryError
+	 * @throws DBError
 	 */
 	public function select(
 		$table, $vars, $conds = '', $fname = __METHOD__,
@@ -799,7 +798,7 @@ interface IDatabase {
 	 * @param array|string $join_conds Join conditions
 	 *
 	 * @return stdClass|bool
-	 * @throws DBQueryError
+	 * @throws DBError
 	 */
 	public function selectRow( $table, $vars, $conds, $fname = __METHOD__,
 		$options = [], $join_conds = []
@@ -824,7 +823,7 @@ interface IDatabase {
 	 * @param string $fname Function name for profiling
 	 * @param array $options Options for select
 	 * @return int Row count
-	 * @throws DBQueryError
+	 * @throws DBError
 	 */
 	public function estimateRowCount(
 		$table, $vars = '*', $conds = '', $fname = __METHOD__, $options = []
@@ -846,7 +845,7 @@ interface IDatabase {
 	 * @param array $options Options for select
 	 * @param array $join_conds Join conditions (since 1.27)
 	 * @return int Row count
-	 * @throws DBQueryError
+	 * @throws DBError
 	 */
 	public function selectRowCount(
 		$tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
@@ -859,6 +858,7 @@ interface IDatabase {
 	 * @param string $field Filed to check on that table
 	 * @param string $fname Calling function name (optional)
 	 * @return bool Whether $table has filed $field
+	 * @throws DBError
 	 */
 	public function fieldExists( $table, $field, $fname = __METHOD__ );
 
@@ -871,6 +871,7 @@ interface IDatabase {
 	 * @param string $index
 	 * @param string $fname
 	 * @return bool|null
+	 * @throws DBError
 	 */
 	public function indexExists( $table, $index, $fname = __METHOD__ );
 
@@ -880,6 +881,7 @@ interface IDatabase {
 	 * @param string $table
 	 * @param string $fname
 	 * @return bool
+	 * @throws DBError
 	 */
 	public function tableExists( $table, $fname = __METHOD__ );
 
@@ -925,6 +927,7 @@ interface IDatabase {
 	 * @param array $options Array of options
 	 *
 	 * @return bool
+	 * @throws DBError
 	 */
 	public function insert( $table, $a, $fname = __METHOD__, $options = [] );
 
@@ -947,6 +950,7 @@ interface IDatabase {
 	 *   - IGNORE: Ignore unique key conflicts
 	 *   - LOW_PRIORITY: MySQL-specific, see MySQL manual.
 	 * @return bool
+	 * @throws DBError
 	 */
 	public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] );
 
@@ -1167,6 +1171,7 @@ interface IDatabase {
 	 * @param array $rows Can be either a single row to insert, or multiple rows,
 	 *    in the same format as for IDatabase::insert()
 	 * @param string $fname Calling function name (use __METHOD__) for logs/profiling
+	 * @throws DBError
 	 */
 	public function replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__ );
 
@@ -1203,7 +1208,7 @@ interface IDatabase {
 	 *   Values with integer keys form unquoted SET statements, which can be used for
 	 *   things like "field = field + 1" or similar computed values.
 	 * @param string $fname Calling function name (use __METHOD__) for logs/profiling
-	 * @throws Exception
+	 * @throws DBError
 	 * @return bool
 	 */
 	public function upsert(
@@ -1228,7 +1233,7 @@ interface IDatabase {
 	 * @param array $conds Condition array of field names mapped to variables,
 	 *   ANDed together in the WHERE clause
 	 * @param string $fname Calling function name (use __METHOD__) for logs/profiling
-	 * @throws DBUnexpectedError
+	 * @throws DBError
 	 */
 	public function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds,
 		$fname = __METHOD__
@@ -1243,6 +1248,7 @@ interface IDatabase {
 	 * @param string $fname Name of the calling function
 	 * @throws DBUnexpectedError
 	 * @return bool|IResultWrapper
+	 * @throws DBError
 	 */
 	public function delete( $table, $conds, $fname = __METHOD__ );
 
@@ -1273,6 +1279,7 @@ interface IDatabase {
 	 *    IDatabase::select() for details.
 	 *
 	 * @return bool
+	 * @throws DBError
 	 */
 	public function insertSelect( $destTable, $srcTable, $varMap, $conds,
 		$fname = __METHOD__,
@@ -1354,6 +1361,7 @@ interface IDatabase {
 	 * Determines how long the server has been up
 	 *
 	 * @return int
+	 * @throws DBError
 	 */
 	public function getServerUptime();
 
@@ -1394,13 +1402,15 @@ interface IDatabase {
 	 * @return int|null Zero if the replica DB was past that position already,
 	 *   greater than zero if we waited for some period of time, less than
 	 *   zero if it timed out, and null on error
+	 * @throws DBError
 	 */
 	public function masterPosWait( DBMasterPos $pos, $timeout );
 
 	/**
 	 * Get the replication position of this replica DB
 	 *
-	 * @return DBMasterPos|bool False if this is not a replica DB.
+	 * @return DBMasterPos|bool False if this is not a replica DB
+	 * @throws DBError
 	 */
 	public function getReplicaPos();
 
@@ -1408,6 +1418,7 @@ interface IDatabase {
 	 * Get the position of this master
 	 *
 	 * @return DBMasterPos|bool False if this is not a master
+	 * @throws DBError
 	 */
 	public function getMasterPos();
 
@@ -1596,7 +1607,7 @@ interface IDatabase {
 	 *   Only set the flush flag if you are sure that these warnings are not applicable,
 	 *   and no explicit transactions are open.
 	 *
-	 * @throws DBUnexpectedError
+	 * @throws DBError
 	 */
 	public function commit( $fname = __METHOD__, $flush = '' );
 
@@ -1617,7 +1628,7 @@ interface IDatabase {
 	 *   constant to disable warnings about calling rollback when no transaction is in
 	 *   progress. This will silently break any ongoing explicit transaction. Only set the
 	 *   flush flag if you are sure that it is safe to ignore these warnings in your context.
-	 * @throws DBUnexpectedError
+	 * @throws DBError
 	 * @since 1.23 Added $flush parameter
 	 */
 	public function rollback( $fname = __METHOD__, $flush = '' );
@@ -1631,7 +1642,7 @@ interface IDatabase {
 	 * useful to call on a replica DB after waiting on replication to catch up to the master.
 	 *
 	 * @param string $fname Calling function name
-	 * @throws DBUnexpectedError
+	 * @throws DBError
 	 * @since 1.28
 	 */
 	public function flushSnapshot( $fname = __METHOD__ );
@@ -1690,6 +1701,7 @@ interface IDatabase {
 	 * instead.
 	 *
 	 * @return int|bool Database replication lag in seconds or false on error
+	 * @throws DBError
 	 */
 	public function getLag();
 
@@ -1704,6 +1716,7 @@ interface IDatabase {
 	 * indication of the staleness of subsequent reads.
 	 *
 	 * @return array ('lag': seconds or false on error, 'since': UNIX timestamp of BEGIN)
+	 * @throws DBError
 	 * @since 1.27
 	 */
 	public function getSessionLagStatus();
@@ -1745,6 +1758,7 @@ interface IDatabase {
 	 *
 	 * @param array $options
 	 * @return void
+	 * @throws DBError
 	 */
 	public function setSessionOptions( array $options );
 
@@ -1763,6 +1777,7 @@ interface IDatabase {
 	 * @param string $lockName Name of lock to poll
 	 * @param string $method Name of method calling us
 	 * @return bool
+	 * @throws DBError
 	 * @since 1.20
 	 */
 	public function lockIsFree( $lockName, $method );
@@ -1776,6 +1791,7 @@ interface IDatabase {
 	 * @param string $method Name of the calling method
 	 * @param int $timeout Acquisition timeout in seconds
 	 * @return bool
+	 * @throws DBError
 	 */
 	public function lock( $lockName, $method, $timeout = 5 );
 
@@ -1788,8 +1804,10 @@ interface IDatabase {
 	 * @param string $method Name of the calling method
 	 *
 	 * @return int Returns 1 if the lock was released, 0 if the lock was not established
-	 * by this thread (in which case the lock is not released), and NULL if the named
-	 * lock did not exist
+	 * by this thread (in which case the lock is not released), and NULL if the named lock
+	 * did not exist
+	 *
+	 * @throws DBError
 	 */
 	public function unlock( $lockName, $method );
 
@@ -1811,7 +1829,7 @@ interface IDatabase {
 	 * @param string $fname Name of the calling method
 	 * @param int $timeout Acquisition timeout in seconds
 	 * @return ScopedCallback|null
-	 * @throws DBUnexpectedError
+	 * @throws DBError
 	 * @since 1.27
 	 */
 	public function getScopedLockAndFlush( $lockKey, $fname, $timeout );