From 3ce1792d97812b27dbf88d8f9be54f956fb0714a Mon Sep 17 00:00:00 2001 From: Aaron Schulz Date: Sat, 3 Mar 2012 19:14:50 +0000 Subject: [PATCH] [FileBackend] * Various documentation improvements. * Moved a few protected FileBackendStoreShardListIterator functions down. Same with normalizeContainerPath(). --- includes/filerepo/backend/FSFileBackend.php | 22 ++++++- includes/filerepo/backend/FileBackend.php | 52 ++++++++-------- .../filerepo/backend/FileBackendStore.php | 59 +++++++++++++------ .../filerepo/backend/SwiftFileBackend.php | 22 ++++++- .../backend/lockmanager/FSLockManager.php | 8 +++ .../backend/lockmanager/LSLockManager.php | 8 +++ .../backend/lockmanager/LockManager.php | 10 +++- 7 files changed, 134 insertions(+), 47 deletions(-) diff --git a/includes/filerepo/backend/FSFileBackend.php b/includes/filerepo/backend/FSFileBackend.php index b863d32ae3..4a27ca117d 100644 --- a/includes/filerepo/backend/FSFileBackend.php +++ b/includes/filerepo/backend/FSFileBackend.php @@ -6,7 +6,7 @@ */ /** - * Class for a file system (FS) based file backend. + * @brief Class for a file system (FS) based file backend. * * All "containers" each map to a directory under the backend's base directory. * For backwards-compatibility, some container paths can be set to custom paths. @@ -579,6 +579,10 @@ class FSFileBackendFileList implements Iterator { } } + /** + * @see Iterator::current() + * @return string|bool String or false + */ public function current() { // Return only the relative path and normalize slashes to FileBackend-style // Make sure to use the realpath since the suffix is based upon that @@ -586,10 +590,18 @@ class FSFileBackendFileList implements Iterator { substr( realpath( $this->iter->current() ), $this->suffixStart ) ); } + /** + * @see Iterator::key() + * @return integer + */ public function key() { return $this->pos; } + /** + * @see Iterator::next() + * @return void + */ public function next() { try { $this->iter->next(); @@ -599,6 +611,10 @@ class FSFileBackendFileList implements Iterator { ++$this->pos; } + /** + * @see Iterator::rewind() + * @return void + */ public function rewind() { $this->pos = 0; try { @@ -608,6 +624,10 @@ class FSFileBackendFileList implements Iterator { } } + /** + * @see Iterator::valid() + * @return bool + */ public function valid() { return $this->iter && $this->iter->valid(); } diff --git a/includes/filerepo/backend/FileBackend.php b/includes/filerepo/backend/FileBackend.php index 35539c5bf1..227941e50b 100644 --- a/includes/filerepo/backend/FileBackend.php +++ b/includes/filerepo/backend/FileBackend.php @@ -14,7 +14,7 @@ */ /** - * Base class for all file backend classes (including multi-write backends). + * @brief Base class for all file backend classes (including multi-write backends). * * This class defines the methods as abstract that subclasses must implement. * Outside callers can assume that all backends will have these functions. @@ -657,6 +657,31 @@ abstract class FileBackend { return null; } + /** + * Get the parent storage directory of a storage path. + * This returns a path like "mwstore://backend/container", + * "mwstore://backend/container/...", or null if there is no parent. + * + * @param $storagePath string + * @return string|null + */ + final public static function parentStoragePath( $storagePath ) { + $storagePath = dirname( $storagePath ); + list( $b, $cont, $rel ) = self::splitStoragePath( $storagePath ); + return ( $rel === null ) ? null : $storagePath; + } + + /** + * Get the final extension from a storage or FS path + * + * @param $path string + * @return string + */ + final public static function extensionFromPath( $path ) { + $i = strrpos( $path, '.' ); + return strtolower( $i ? substr( $path, $i + 1 ) : '' ); + } + /** * Validate and normalize a relative storage path. * Null is returned if the path involves directory traversal. @@ -687,29 +712,4 @@ abstract class FileBackend { } return $path; } - - /** - * Get the parent storage directory of a storage path. - * This returns a path like "mwstore://backend/container", - * "mwstore://backend/container/...", or null if there is no parent. - * - * @param $storagePath string - * @return string|null - */ - final public static function parentStoragePath( $storagePath ) { - $storagePath = dirname( $storagePath ); - list( $b, $cont, $rel ) = self::splitStoragePath( $storagePath ); - return ( $rel === null ) ? null : $storagePath; - } - - /** - * Get the final extension from a storage or FS path - * - * @param $path string - * @return string - */ - final public static function extensionFromPath( $path ) { - $i = strrpos( $path, '.' ); - return strtolower( $i ? substr( $path, $i + 1 ) : '' ); - } } diff --git a/includes/filerepo/backend/FileBackendStore.php b/includes/filerepo/backend/FileBackendStore.php index d395eac417..4f4a185fcc 100644 --- a/includes/filerepo/backend/FileBackendStore.php +++ b/includes/filerepo/backend/FileBackendStore.php @@ -997,6 +997,10 @@ class FileBackendStoreShardListIterator implements Iterator { $this->params = $params; } + /** + * @see Iterator::current() + * @return string|bool String or false + */ public function current() { if ( is_array( $this->iter ) ) { return current( $this->iter ); @@ -1005,10 +1009,18 @@ class FileBackendStoreShardListIterator implements Iterator { } } + /** + * @see Iterator::key() + * @return integer + */ public function key() { return $this->pos; } + /** + * @see Iterator::next() + * @return void + */ public function next() { ++$this->pos; if ( is_array( $this->iter ) ) { @@ -1021,25 +1033,9 @@ class FileBackendStoreShardListIterator implements Iterator { } /** - * If the iterator for this container shard is out of items, - * then move on to the next container that has items. - * If there are none, then it advances to the last container. + * @see Iterator::rewind() + * @return void */ - protected function nextShardIteratorIfNotValid() { - while ( !$this->valid() ) { - if ( ++$this->curShard >= count( $this->shardSuffixes ) ) { - break; // no more container shards - } - $this->setIteratorFromCurrentShard(); - } - } - - protected function setIteratorFromCurrentShard() { - $suffix = $this->shardSuffixes[$this->curShard]; - $this->iter = $this->backend->getFileListInternal( - "{$this->container}{$suffix}", $this->directory, $this->params ); - } - public function rewind() { $this->pos = 0; $this->curShard = 0; @@ -1048,6 +1044,10 @@ class FileBackendStoreShardListIterator implements Iterator { $this->nextShardIteratorIfNotValid(); } + /** + * @see Iterator::valid() + * @return bool + */ public function valid() { if ( $this->iter == null ) { return false; // some failure? @@ -1057,4 +1057,27 @@ class FileBackendStoreShardListIterator implements Iterator { return $this->iter->valid(); } } + + /** + * If the list iterator for this container shard is out of items, + * then move on to the next container that has items. + * If there are none, then it advances to the last container. + */ + protected function nextShardIteratorIfNotValid() { + while ( !$this->valid() ) { + if ( ++$this->curShard >= count( $this->shardSuffixes ) ) { + break; // no more container shards + } + $this->setIteratorFromCurrentShard(); + } + } + + /** + * Set the list iterator to that of the current container shard + */ + protected function setIteratorFromCurrentShard() { + $suffix = $this->shardSuffixes[$this->curShard]; + $this->iter = $this->backend->getFileListInternal( + "{$this->container}{$suffix}", $this->directory, $this->params ); + } } diff --git a/includes/filerepo/backend/SwiftFileBackend.php b/includes/filerepo/backend/SwiftFileBackend.php index 86ab1beddf..3ad78e3abb 100644 --- a/includes/filerepo/backend/SwiftFileBackend.php +++ b/includes/filerepo/backend/SwiftFileBackend.php @@ -7,7 +7,7 @@ */ /** - * Class for an OpenStack Swift based file backend. + * @brief Class for an OpenStack Swift based file backend. * * This requires the SwiftCloudFiles MediaWiki extension, which includes * the php-cloudfiles library (https://github.com/rackspace/php-cloudfiles). @@ -856,14 +856,26 @@ class SwiftFileBackendFileList implements Iterator { } } + /** + * @see Iterator::current() + * @return string|bool String or false + */ public function current() { return substr( current( $this->bufferIter ), $this->suffixStart ); } + /** + * @see Iterator::key() + * @return integer + */ public function key() { return $this->pos; } + /** + * @see Iterator::next() + * @return void + */ public function next() { // Advance to the next file in the page next( $this->bufferIter ); @@ -878,6 +890,10 @@ class SwiftFileBackendFileList implements Iterator { } } + /** + * @see Iterator::rewind() + * @return void + */ public function rewind() { $this->pos = 0; $this->bufferAfter = null; @@ -886,6 +902,10 @@ class SwiftFileBackendFileList implements Iterator { ); } + /** + * @see Iterator::valid() + * @return bool + */ public function valid() { return ( current( $this->bufferIter ) !== false ); // no paths can have this value } diff --git a/includes/filerepo/backend/lockmanager/FSLockManager.php b/includes/filerepo/backend/lockmanager/FSLockManager.php index 42074fd3fb..c14b8d0aa8 100644 --- a/includes/filerepo/backend/lockmanager/FSLockManager.php +++ b/includes/filerepo/backend/lockmanager/FSLockManager.php @@ -38,6 +38,10 @@ class FSLockManager extends LockManager { $this->lockDir = $config['lockDirectory']; } + /** + * @see LockManager::doLock() + * @return Status + */ protected function doLock( array $paths, $type ) { $status = Status::newGood(); @@ -56,6 +60,10 @@ class FSLockManager extends LockManager { return $status; } + /** + * @see LockManager::doUnlock() + * @return Status + */ protected function doUnlock( array $paths, $type ) { $status = Status::newGood(); diff --git a/includes/filerepo/backend/lockmanager/LSLockManager.php b/includes/filerepo/backend/lockmanager/LSLockManager.php index c1b741fde8..a77c3a283e 100644 --- a/includes/filerepo/backend/lockmanager/LSLockManager.php +++ b/includes/filerepo/backend/lockmanager/LSLockManager.php @@ -68,6 +68,10 @@ class LSLockManager extends LockManager { $this->session = wfBaseConvert( sha1( $this->session ), 16, 36, 31 ); } + /** + * @see LockManager::doLock() + * @return Status + */ protected function doLock( array $paths, $type ) { $status = Status::newGood(); @@ -117,6 +121,10 @@ class LSLockManager extends LockManager { return $status; } + /** + * @see LockManager::doUnlock() + * @return Status + */ protected function doUnlock( array $paths, $type ) { $status = Status::newGood(); diff --git a/includes/filerepo/backend/lockmanager/LockManager.php b/includes/filerepo/backend/lockmanager/LockManager.php index be071c51e9..506d8504ea 100644 --- a/includes/filerepo/backend/lockmanager/LockManager.php +++ b/includes/filerepo/backend/lockmanager/LockManager.php @@ -11,7 +11,7 @@ */ /** - * Class for handling resource locking. + * @brief Class for handling resource locking. * * Locks on resource keys can either be shared or exclusive. * @@ -178,10 +178,18 @@ class ScopedLock { * @since 1.19 */ class NullLockManager extends LockManager { + /** + * @see LockManager::doLock() + * @return Status + */ protected function doLock( array $paths, $type ) { return Status::newGood(); } + /** + * @see LockManager::doUnlock() + * @return Status + */ protected function doUnlock( array $paths, $type ) { return Status::newGood(); } -- 2.20.1