From 9eb1554fadf79af54c465f0729ab1de9f24e447d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Thu, 28 Nov 2019 14:17:15 +0100 Subject: [PATCH] Properly anotate LockedException in files node api MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julius Härtl --- lib/private/Files/Node/File.php | 15 ++++++++++++--- lib/private/Files/Node/Node.php | 23 +++++++++++++++++------ lib/private/Files/View.php | 24 +++++++++++++++--------- lib/public/Files/File.php | 13 +++++++++---- lib/public/Files/Node.php | 29 ++++++++++++++++++++--------- 5 files changed, 73 insertions(+), 31 deletions(-) diff --git a/lib/private/Files/Node/File.php b/lib/private/Files/Node/File.php index b504c7a29d..e4669f7070 100644 --- a/lib/private/Files/Node/File.php +++ b/lib/private/Files/Node/File.php @@ -28,6 +28,7 @@ namespace OC\Files\Node; use OCP\Files\GenericFileException; use OCP\Files\NotPermittedException; +use OCP\Lock\LockedException; class File extends Node implements \OCP\Files\File { /** @@ -42,7 +43,8 @@ class File extends Node implements \OCP\Files\File { /** * @return string - * @throws \OCP\Files\NotPermittedException + * @throws NotPermittedException + * @throws LockedException */ public function getContent() { if ($this->checkPermissions(\OCP\Constants::PERMISSION_READ)) { @@ -57,8 +59,9 @@ class File extends Node implements \OCP\Files\File { /** * @param string|resource $data - * @throws \OCP\Files\NotPermittedException + * @throws NotPermittedException * @throws \OCP\Files\GenericFileException + * @throws LockedException */ public function putContent($data) { if ($this->checkPermissions(\OCP\Constants::PERMISSION_UPDATE)) { @@ -76,7 +79,8 @@ class File extends Node implements \OCP\Files\File { /** * @param string $mode * @return resource - * @throws \OCP\Files\NotPermittedException + * @throws NotPermittedException + * @throws LockedException */ public function fopen($mode) { $preHooks = array(); @@ -113,6 +117,11 @@ class File extends Node implements \OCP\Files\File { } } + /** + * @throws NotPermittedException + * @throws \OCP\Files\InvalidPathException + * @throws \OCP\Files\NotFoundException + */ public function delete() { if ($this->checkPermissions(\OCP\Constants::PERMISSION_DELETE)) { $this->sendHooks(array('preDelete')); diff --git a/lib/private/Files/Node/Node.php b/lib/private/Files/Node/Node.php index 95d16cf5c9..7f50524f28 100644 --- a/lib/private/Files/Node/Node.php +++ b/lib/private/Files/Node/Node.php @@ -33,6 +33,7 @@ use OCP\Files\FileInfo; use OCP\Files\InvalidPathException; use OCP\Files\NotFoundException; use OCP\Files\NotPermittedException; +use OCP\Lock\LockedException; use Symfony\Component\EventDispatcher\GenericEvent; // FIXME: this class really should be abstract @@ -75,6 +76,7 @@ class Node implements \OCP\Files\Node { * * @param string $path path * @return string non-existing node class + * @throws \Exception */ protected function createNonExistingNode($path) { throw new \Exception('Must be implemented by subclasses'); @@ -117,6 +119,8 @@ class Node implements \OCP\Files\Node { /** * @param int $permissions * @return bool + * @throws InvalidPathException + * @throws NotFoundException */ protected function checkPermissions($permissions) { return ($this->getPermissions() & $permissions) === $permissions; @@ -127,7 +131,9 @@ class Node implements \OCP\Files\Node { /** * @param int $mtime - * @throws \OCP\Files\NotPermittedException + * @throws InvalidPathException + * @throws NotFoundException + * @throws NotPermittedException */ public function touch($mtime = null) { if ($this->checkPermissions(\OCP\Constants::PERMISSION_UPDATE)) { @@ -366,7 +372,7 @@ class Node implements \OCP\Files\Node { /** * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @throws \OCP\Lock\LockedException + * @throws LockedException */ public function lock($type) { $this->view->lockFile($this->path, $type); @@ -374,7 +380,7 @@ class Node implements \OCP\Files\Node { /** * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @throws \OCP\Lock\LockedException + * @throws LockedException */ public function changeLock($type) { $this->view->changeLock($this->path, $type); @@ -382,7 +388,7 @@ class Node implements \OCP\Files\Node { /** * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @throws \OCP\Lock\LockedException + * @throws LockedException */ public function unlock($type) { $this->view->unlockFile($this->path, $type); @@ -390,8 +396,10 @@ class Node implements \OCP\Files\Node { /** * @param string $targetPath - * @throws \OCP\Files\NotPermittedException if copy not allowed or failed * @return \OC\Files\Node\Node + * @throws InvalidPathException + * @throws NotFoundException + * @throws NotPermittedException if copy not allowed or failed */ public function copy($targetPath) { $targetPath = $this->normalizePath($targetPath); @@ -414,8 +422,11 @@ class Node implements \OCP\Files\Node { /** * @param string $targetPath - * @throws \OCP\Files\NotPermittedException if move not allowed or failed * @return \OC\Files\Node\Node + * @throws InvalidPathException + * @throws NotFoundException + * @throws NotPermittedException if move not allowed or failed + * @throws LockedException */ public function move($targetPath) { $targetPath = $this->normalizePath($targetPath); diff --git a/lib/private/Files/View.php b/lib/private/Files/View.php index 4f4c4b90f2..ed962bde1a 100644 --- a/lib/private/Files/View.php +++ b/lib/private/Files/View.php @@ -589,6 +589,7 @@ class View { /** * @param string $path * @return mixed + * @throws LockedException */ public function file_get_contents($path) { return $this->basicOperation('file_get_contents', $path, array('read')); @@ -640,7 +641,7 @@ class View { * @param string $path * @param string|resource $data * @return bool|mixed - * @throws \Exception + * @throws LockedException */ public function file_put_contents($path, $data) { if (is_resource($data)) { //not having to deal with streams in file_put_contents makes life easier @@ -739,6 +740,7 @@ class View { * @param string $path2 target path * * @return bool|mixed + * @throws LockedException */ public function rename($path1, $path2) { $absolutePath1 = Filesystem::normalizePath($this->getAbsolutePath($path1)); @@ -962,6 +964,7 @@ class View { * @param string $path * @param string $mode 'r' or 'w' * @return resource + * @throws LockedException */ public function fopen($path, $mode) { $mode = str_replace('b', '', $mode); // the binary flag is a windows only feature which we do not support @@ -1117,7 +1120,7 @@ class View { * @param array $hooks (optional) * @param mixed $extraParam (optional) * @return mixed - * @throws \Exception + * @throws LockedException * * This method takes requests for basic filesystem functions (e.g. reading & writing * files), processes hooks and proxies, sanitises paths, and finally passes them on to @@ -1919,7 +1922,7 @@ class View { * @param bool $lockMountPoint true to lock the mount point, false to lock the attached mount/storage * * @return bool False if the path is excluded from locking, true otherwise - * @throws \OCP\Lock\LockedException if the path is already locked + * @throws LockedException if the path is already locked */ private function lockPath($path, $type, $lockMountPoint = false) { $absolutePath = $this->getAbsolutePath($path); @@ -1939,9 +1942,9 @@ class View { $this->lockingProvider ); } - } catch (\OCP\Lock\LockedException $e) { + } catch (LockedException $e) { // rethrow with the a human-readable path - throw new \OCP\Lock\LockedException( + throw new LockedException( $this->getPathRelativeToFiles($absolutePath), $e ); @@ -1959,7 +1962,7 @@ class View { * @param bool $lockMountPoint true to lock the mount point, false to lock the attached mount/storage * * @return bool False if the path is excluded from locking, true otherwise - * @throws \OCP\Lock\LockedException if the path is already locked + * @throws LockedException if the path is already locked */ public function changeLock($path, $type, $lockMountPoint = false) { $path = Filesystem::normalizePath($path); @@ -1980,15 +1983,15 @@ class View { $this->lockingProvider ); } - } catch (\OCP\Lock\LockedException $e) { + } catch (LockedException $e) { try { // rethrow with the a human-readable path - throw new \OCP\Lock\LockedException( + throw new LockedException( $this->getPathRelativeToFiles($absolutePath), $e ); } catch (\InvalidArgumentException $e) { - throw new \OCP\Lock\LockedException( + throw new LockedException( $absolutePath, $e ); @@ -2007,6 +2010,7 @@ class View { * @param bool $lockMountPoint true to lock the mount point, false to lock the attached mount/storage * * @return bool False if the path is excluded from locking, true otherwise + * @throws LockedException */ private function unlockPath($path, $type, $lockMountPoint = false) { $absolutePath = $this->getAbsolutePath($path); @@ -2038,6 +2042,7 @@ class View { * @param bool $lockMountPoint true to lock the mount point, false to lock the attached mount/storage * * @return bool False if the path is excluded from locking, true otherwise + * @throws LockedException */ public function lockFile($path, $type, $lockMountPoint = false) { $absolutePath = $this->getAbsolutePath($path); @@ -2064,6 +2069,7 @@ class View { * @param bool $lockMountPoint true to lock the mount point, false to lock the attached mount/storage * * @return bool False if the path is excluded from locking, true otherwise + * @throws LockedException */ public function unlockFile($path, $type, $lockMountPoint = false) { $absolutePath = $this->getAbsolutePath($path); diff --git a/lib/public/Files/File.php b/lib/public/Files/File.php index 1fe01cfb29..bd3b3da0df 100644 --- a/lib/public/Files/File.php +++ b/lib/public/Files/File.php @@ -33,6 +33,8 @@ namespace OCP\Files; +use OCP\Lock\LockedException; + /** * Interface File * @@ -44,7 +46,8 @@ interface File extends Node { * Get the content of the file as string * * @return string - * @throws \OCP\Files\NotPermittedException + * @throws NotPermittedException + * @throws LockedException * @since 6.0.0 */ public function getContent(); @@ -53,8 +56,9 @@ interface File extends Node { * Write to the file from string data * * @param string|resource $data - * @throws \OCP\Files\NotPermittedException - * @throws \OCP\Files\GenericFileException + * @throws NotPermittedException + * @throws GenericFileException + * @throws LockedException * @since 6.0.0 */ public function putContent($data); @@ -72,7 +76,8 @@ interface File extends Node { * * @param string $mode * @return resource - * @throws \OCP\Files\NotPermittedException + * @throws NotPermittedException + * @throws LockedException * @since 6.0.0 */ public function fopen($mode); diff --git a/lib/public/Files/Node.php b/lib/public/Files/Node.php index 4468b68001..af7d9454ca 100644 --- a/lib/public/Files/Node.php +++ b/lib/public/Files/Node.php @@ -34,6 +34,8 @@ namespace OCP\Files; +use OCP\Lock\LockedException; + /** * Interface Node * @@ -45,15 +47,22 @@ interface Node extends FileInfo { * Move the file or folder to a new location * * @param string $targetPath the absolute target path - * @throws \OCP\Files\NotPermittedException - * @return \OCP\Files\Node + * @return Node + * @throws NotFoundException + * @throws NotPermittedException if move not allowed or failed + * @throws LockedException + * @throws InvalidPathException * @since 6.0.0 */ public function move($targetPath); /** * Delete the file or folder + * * @return void + * @throws NotPermittedException + * @throws InvalidPathException + * @throws NotFoundException * @since 6.0.0 */ public function delete(); @@ -62,7 +71,7 @@ interface Node extends FileInfo { * Cope the file or folder to a new location * * @param string $targetPath the absolute target path - * @return \OCP\Files\Node + * @return Node * @since 6.0.0 */ public function copy($targetPath); @@ -72,7 +81,9 @@ interface Node extends FileInfo { * If $mtime is omitted the current time will be used * * @param int $mtime (optional) modified date as unix timestamp - * @throws \OCP\Files\NotPermittedException + * @throws InvalidPathException + * @throws NotFoundException + * @throws NotPermittedException * @return void * @since 6.0.0 */ @@ -81,8 +92,8 @@ interface Node extends FileInfo { /** * Get the storage backend the file or folder is stored on * - * @return \OCP\Files\Storage - * @throws \OCP\Files\NotFoundException + * @return Storage + * @throws NotFoundException * @since 6.0.0 */ public function getStorage(); @@ -247,7 +258,7 @@ interface Node extends FileInfo { * any filesystem operation will automatically acquire the relevant locks for that operation. * * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @throws \OCP\Lock\LockedException + * @throws LockedException * @since 9.1.0 */ public function lock($type); @@ -262,7 +273,7 @@ interface Node extends FileInfo { * Note that this is also the case if no existing lock exists for the file. * * @param int $targetType \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @throws \OCP\Lock\LockedException + * @throws LockedException * @since 9.1.0 */ public function changeLock($targetType); @@ -275,7 +286,7 @@ interface Node extends FileInfo { * Note that this method will not give any sort of error when trying to free a lock that doesn't exist. * * @param int $type \OCP\Lock\ILockingProvider::LOCK_SHARED or \OCP\Lock\ILockingProvider::LOCK_EXCLUSIVE - * @throws \OCP\Lock\LockedException + * @throws LockedException * @since 9.1.0 */ public function unlock($type);