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 e04566e..9875d93 100644 (file)
--- 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 bbf88dc..6047fb0 100644 (file)
--- 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 );