[Pkg-owncloud-commits] [owncloud] 81/122: improve phpdoc of cache classes
David Prévot
taffit at moszumanska.debian.org
Sat May 9 00:00:19 UTC 2015
This is an automated email from the git hooks/post-receive script.
taffit pushed a commit to branch stable8
in repository owncloud.
commit e0d151505f44fa58250cb120763b94963fe44f82
Author: Robin Appelman <icewind at owncloud.com>
Date: Tue May 5 16:06:28 2015 +0200
improve phpdoc of cache classes
---
lib/private/files/cache/cache.php | 112 ++++++++++++++++++++++++++++++------
lib/private/files/cache/storage.php | 26 +++++++--
lib/private/files/cache/updater.php | 30 ++++++++--
lib/public/files/storage.php | 1 -
4 files changed, 139 insertions(+), 30 deletions(-)
diff --git a/lib/private/files/cache/cache.php b/lib/private/files/cache/cache.php
index 7d3738f..a82ccec 100644
--- a/lib/private/files/cache/cache.php
+++ b/lib/private/files/cache/cache.php
@@ -35,9 +35,14 @@
namespace OC\Files\Cache;
/**
- * Metadata cache for the filesystem
+ * Metadata cache for a storage
*
- * don't use this class directly if you need to get metadata, use \OC\Files\Filesystem::getFileInfo instead
+ * The cache stores the metadata for all files and folders in a storage and is kept up to date trough the following mechanisms:
+ *
+ * - Scanner: scans the storage and updates the cache where needed
+ * - Watcher: checks for changes made to the filesystem outside of the ownCloud instance and rescans files and folder when a change is detected
+ * - Updater: listens to changes made to the filesystem inside of the ownCloud instance and updates the cache where needed
+ * - ChangePropagator: updates the mtime and etags of parent folders whenever a change to the cache is made to the cache by the updater
*/
class Cache {
const NOT_FOUND = 0;
@@ -79,12 +84,20 @@ class Cache {
$this->storageCache = new Storage($storage);
}
+ /**
+ * Get the numeric storage id for this cache's storage
+ *
+ * @return int
+ */
public function getNumericStorageId() {
return $this->storageCache->getNumericId();
}
/**
- * normalize mimetypes
+ * Get the numeric id for a mimetype
+ *
+ * Mimetypes are stored as integers in the cache to prevent duplicated data of the (usually) fairly limited amount of unique mimetypes
+ * If the supplied mimetype does not yet have a numeric id a new one will be generated
*
* @param string $mime
* @return int
@@ -114,6 +127,13 @@ class Cache {
return self::$mimetypeIds[$mime];
}
+
+ /**
+ * Get the mimetype (as string) from a mimetype id
+ *
+ * @param int $id
+ * @return string | null the mimetype for the id or null if the id is not known
+ */
public function getMimetype($id) {
if (empty(self::$mimetypes)) {
$this->loadMimetypes();
@@ -122,6 +142,11 @@ class Cache {
return isset(self::$mimetypes[$id]) ? self::$mimetypes[$id] : null;
}
+ /**
+ * Load all known mimetypes and mimetype ids from the database
+ *
+ * @throws \OC\DatabaseException
+ */
public function loadMimetypes() {
self::$mimetypeIds = self::$mimetypes = array();
@@ -137,8 +162,28 @@ class Cache {
/**
* get the stored metadata of a file or folder
*
- * @param string /int $file
- * @return array|false
+ * the returned cache entry contains at least the following values:
+ * [
+ * 'fileid' => int, the numeric id of a file (see getId)
+ * 'storage' => int, the numeric id of the storage the file is stored on
+ * 'path' => string, the path of the file within the storage ('foo/bar.txt')
+ * 'name' => string, the basename of a file ('bar.txt)
+ * 'mimetype' => string, the full mimetype of the file ('text/plain')
+ * 'mimepart' => string, the first half of the mimetype ('text')
+ * 'size' => int, the size of the file or folder in bytes
+ * 'mtime' => int, the last modified date of the file as unix timestamp as shown in the ui
+ * 'storage_mtime' => int, the last modified date of the file as unix timestamp as stored on the storage
+ * Note that when a file is updated we also update the mtime of all parent folders to make it visible to the user which folder has had updates most recently
+ * This can differ from the mtime on the underlying storage which usually only changes when a direct child is added, removed or renamed
+ * 'etag' => string, the etag for the file
+ * An etag is used for change detection of files and folders, an etag of a file changes whenever the content of the file changes
+ * Etag for folders change whenever a file in the folder has changed
+ * 'permissions' int, the permissions for the file stored as bitwise combination of \OCP\PERMISSION_READ, \OCP\PERMISSION_CREATE
+ * \OCP\PERMISSION_UPDATE, \OCP\PERMISSION_DELETE and \OCP\PERMISSION_SHARE
+ * ]
+ *
+ * @param string | int $file either the path of a file or folder or the file id for a file or folder
+ * @return array|false the cache entry as array of false if the file is not found in the cache
*/
public function get($file) {
if (is_string($file) or $file == '') {
@@ -288,10 +333,10 @@ class Cache {
}
/**
- * update the metadata in the cache
+ * update the metadata of an existing file or folder in the cache
*
- * @param int $id
- * @param array $data
+ * @param int $id the fileid of the existing file or folder
+ * @param array $data [$key => $value] the metadata to update, only the fields provided in the array will be updated, non-provided values will remain unchanged
*/
public function update($id, array $data) {
@@ -323,9 +368,11 @@ class Cache {
* extract query parts and params array from data array
*
* @param array $data
- * @return array
+ * @return array [$queryParts, $params]
+ * $queryParts: string[], the (escaped) column names to be set in the query
+ * $params: mixed[], the new values for the columns, to be passed as params to the query
*/
- function buildParts(array $data) {
+ protected function buildParts(array $data) {
$fields = array(
'path', 'parent', 'name', 'mimetype', 'size', 'mtime', 'storage_mtime', 'encrypted',
'etag', 'permissions');
@@ -359,6 +406,10 @@ class Cache {
/**
* get the file id for a file
*
+ * A file id is a numeric id for a file or folder that's unique within an owncloud instance which stays the same for the lifetime of a file
+ *
+ * File ids are easiest way for apps to store references to a file since unlike paths they are not affected by renames or sharing
+ *
* @param string $file
* @return int
*/
@@ -408,6 +459,8 @@ class Cache {
/**
* remove a file or folder from the cache
*
+ * when removing a folder from the cache all files and folders inside the folder will be removed as well
+ *
* @param string $file
*/
public function remove($file) {
@@ -419,6 +472,12 @@ class Cache {
}
}
+ /**
+ * Get all sub folders of a folder
+ *
+ * @param array $entry the cache entry of the folder to get the subfolders for
+ * @return array[] the cache entries for the subfolders
+ */
private function getSubFolders($entry) {
$children = $this->getFolderContentsById($entry['fileid']);
return array_filter($children, function ($child) {
@@ -426,6 +485,12 @@ class Cache {
});
}
+ /**
+ * Recursively remove all children of a folder
+ *
+ * @param array $entry the cache entry of the folder to remove the children of
+ * @throws \OC\DatabaseException
+ */
private function removeChildren($entry) {
$subFolders = $this->getSubFolders($entry);
foreach ($subFolders as $folder) {
@@ -507,6 +572,13 @@ class Cache {
}
/**
+ * Get the scan status of a file
+ *
+ * - Cache::NOT_FOUND: File is not in the cache
+ * - Cache::PARTIAL: File is not stored in the cache but some incomplete data is known
+ * - Cache::SHALLOW: The folder and it's direct children are in the cache but not all sub folders are fully scanned
+ * - Cache::COMPLETE: The file or folder, with all it's children) are fully scanned
+ *
* @param string $file
*
* @return int Cache::NOT_FOUND, Cache::PARTIAL, Cache::SHALLOW or Cache::COMPLETE
@@ -536,8 +608,8 @@ class Cache {
/**
* search for files matching $pattern
*
- * @param string $pattern
- * @return array an array of file data
+ * @param string $pattern the search pattern using SQL search syntax (e.g. '%searchstring%')
+ * @return array an array of cache entries where the name matches the search pattern
*/
public function search($pattern) {
@@ -567,8 +639,9 @@ class Cache {
/**
* search for files by mimetype
*
- * @param string $mimetype
- * @return array
+ * @param string $mimetype either a full mimetype to search ('text/plain') or only the first part of a mimetype ('image')
+ * where it will search for all mimetypes in the group ('image/*')
+ * @return array an array of cache entries where the mimetype matches the search
*/
public function searchByMime($mimetype) {
if (strpos($mimetype, '/')) {
@@ -635,7 +708,7 @@ class Cache {
}
/**
- * update the folder size and the size of all parent folders
+ * Re-calculate the folder size and the size of all parent folders
*
* @param string|boolean $path
* @param array $data (optional) meta data of the folder
@@ -652,7 +725,7 @@ class Cache {
}
/**
- * get the size of a folder and set it in the cache
+ * calculate the size of a folder and set it in the cache
*
* @param string $path
* @param array $entry (optional) meta data of the folder
@@ -729,10 +802,10 @@ class Cache {
}
/**
- * get the path of a file on this storage by it's id
+ * get the path of a file on this storage by it's file id
*
- * @param int $id
- * @return string|null
+ * @param int $id the file id of the file or folder to search
+ * @return string|null the path of the file (relative to the storage) or null if a file with the given id does not exists within this cache
*/
public function getPathById($id) {
$sql = 'SELECT `path` FROM `*PREFIX*filecache` WHERE `fileid` = ? AND `storage` = ?';
@@ -754,6 +827,7 @@ class Cache {
* instead does a global search in the cache table
*
* @param int $id
+ * @deprecated use getPathById() instead
* @return array first element holding the storage id, second the path
*/
static public function getById($id) {
diff --git a/lib/private/files/cache/storage.php b/lib/private/files/cache/storage.php
index 2007f0c..ebef245 100644
--- a/lib/private/files/cache/storage.php
+++ b/lib/private/files/cache/storage.php
@@ -27,9 +27,13 @@
namespace OC\Files\Cache;
/**
- * Class Storage
+ * Handle the mapping between the string and numeric storage ids
*
- * cache storage specific data
+ * Each storage has 2 different ids
+ * a string id which is generated by the storage backend and reflects the configuration of the storage (e.g. 'smb://user@host/share')
+ * and a numeric storage id which is referenced in the file cache
+ *
+ * A mapping between the two storage ids is stored in the database and accessible trough this class
*
* @package OC\Files\Cache
*/
@@ -71,7 +75,7 @@ class Storage {
/**
* Adjusts the storage id to use md5 if too long
* @param string $storageId storage id
- * @return unchanged $storageId if its length is less than 64 characters,
+ * @return string unchanged $storageId if its length is less than 64 characters,
* else returns the md5 of $storageId
*/
public static function adjustStorageId($storageId) {
@@ -82,14 +86,19 @@ class Storage {
}
/**
- * @return string
+ * Get the numeric id for the storage
+ *
+ * @return int
*/
public function getNumericId() {
return $this->numericId;
}
/**
- * @return string|null
+ * Get the string id for the storage
+ *
+ * @param int $numericId
+ * @return string|null either the storage id string or null if the numeric id is not known
*/
public static function getStorageId($numericId) {
@@ -103,7 +112,10 @@ class Storage {
}
/**
- * @return string|null
+ * Get the numeric of the storage with the provided string id
+ *
+ * @param $storageId
+ * @return int|null either the numeric storage id or null if the storage id is not knwon
*/
public static function getNumericStorageId($storageId) {
$storageId = self::adjustStorageId($storageId);
@@ -118,6 +130,8 @@ class Storage {
}
/**
+ * Check if a string storage id is known
+ *
* @param string $storageId
* @return bool
*/
diff --git a/lib/private/files/cache/updater.php b/lib/private/files/cache/updater.php
index 6634535..7df223e 100644
--- a/lib/private/files/cache/updater.php
+++ b/lib/private/files/cache/updater.php
@@ -27,6 +27,9 @@ namespace OC\Files\Cache;
/**
* Update the cache and propagate changes
+ *
+ * Unlike most other classes an Updater is not related to a specific storage but handles updates for all storages in a users filesystem.
+ * This is needed because the propagation of mtime and etags need to cross storage boundaries
*/
class Updater {
/**
@@ -45,25 +48,42 @@ class Updater {
protected $propagator;
/**
- * @param \OC\Files\View $view
+ * @param \OC\Files\View $view the view the updater works on, usually the view of the logged in user
*/
public function __construct($view) {
$this->view = $view;
$this->propagator = new ChangePropagator($view);
}
+ /**
+ * Disable updating the cache trough this updater
+ */
public function disable() {
$this->enabled = false;
}
+ /**
+ * Re-enable the updating of the cache trough this updater
+ */
public function enable() {
$this->enabled = true;
}
+ /**
+ * Get the propagator for etags and mtime for the view the updater works on
+ *
+ * @return ChangePropagator
+ */
public function getPropagator() {
return $this->propagator;
}
+ /**
+ * Propagate etag and mtime changes for the parent folders of $path up to the root of the filesystem
+ *
+ * @param string $path the path of the file to propagate the changes for
+ * @param int|null $time the timestamp to set as mtime for the parent folders, if left out the current time is used
+ */
public function propagate($path, $time = null) {
if (Scanner::isPartialFile($path)) {
return;
@@ -73,7 +93,7 @@ class Updater {
}
/**
- * Update the cache for $path
+ * Update the cache for $path and update the size, etag and mtime of the parent folders
*
* @param string $path
* @param int $time
@@ -99,7 +119,7 @@ class Updater {
}
/**
- * Remove $path from the cache
+ * Remove $path from the cache and update the size, etag and mtime of the parent folders
*
* @param string $path
*/
@@ -127,6 +147,8 @@ class Updater {
}
/**
+ * Rename a file or folder in the cache and update the size, etag and mtime of the parent folders
+ *
* @param string $source
* @param string $target
*/
@@ -176,7 +198,7 @@ class Updater {
}
/**
- * update the storage_mtime of the parent
+ * update the storage_mtime of the direct parent in the cache to the mtime from the storage
*
* @param \OC\Files\Storage\Storage $storage
* @param string $internalPath
diff --git a/lib/public/files/storage.php b/lib/public/files/storage.php
index 17e09af..b89fb49 100644
--- a/lib/public/files/storage.php
+++ b/lib/public/files/storage.php
@@ -45,7 +45,6 @@ interface Storage {
* $parameters is a free form array with the configuration options needed to construct the storage
*
* @param array $parameters
- * @return void
* @since 6.0.0
*/
public function __construct($parameters);
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-owncloud/owncloud.git
More information about the Pkg-owncloud-commits
mailing list