Move \OCP\Files to PSR-4

6 files changed, 664 insertions, 0 deletions

diff --git a/lib/public/Files/Cache/ICache.php b/lib/public/Files/Cache/ICache.php
new file mode 100644
index 00000000000..4ef88f6480f
--- /dev/null
+++ b/lib/public/Files/Cache/ICache.php
@@ -0,0 +1,256 @@
+<?php
+/**
+ * @author Robin Appelman <icewind@owncloud.com>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+namespace OCP\Files\Cache;
+
+/**
+ * Metadata cache for a storage
+ *
+ * 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
+ *
+ * @since 9.0.0
+ */
+interface ICache {
+	const NOT_FOUND = 0;
+	const PARTIAL = 1; //only partial data available, file not cached in the database
+	const SHALLOW = 2; //folder in cache, but not all child files are completely scanned
+	const COMPLETE = 3;
+
+	/**
+	 * Get the numeric storage id for this cache's storage
+	 *
+	 * @return int
+	 * @since 9.0.0
+	 */
+	public function getNumericStorageId();
+
+	/**
+	 * get the stored metadata of a file or folder
+	 *
+	 * @param string | int $file either the path of a file or folder or the file id for a file or folder
+	 * @return ICacheEntry|false the cache entry or false if the file is not found in the cache
+	 * @since 9.0.0
+	 */
+	public function get($file);
+
+	/**
+	 * get the metadata of all files stored in $folder
+	 *
+	 * Only returns files one level deep, no recursion
+	 *
+	 * @param string $folder
+	 * @return ICacheEntry[]
+	 * @since 9.0.0
+	 */
+	public function getFolderContents($folder);
+
+	/**
+	 * get the metadata of all files stored in $folder
+	 *
+	 * Only returns files one level deep, no recursion
+	 *
+	 * @param int $fileId the file id of the folder
+	 * @return ICacheEntry[]
+	 * @since 9.0.0
+	 */
+	public function getFolderContentsById($fileId);
+
+	/**
+	 * store meta data for a file or folder
+	 * This will automatically call either insert or update depending on if the file exists
+	 *
+	 * @param string $file
+	 * @param array $data
+	 *
+	 * @return int file id
+	 * @throws \RuntimeException
+	 * @since 9.0.0
+	 */
+	public function put($file, array $data);
+
+	/**
+	 * insert meta data for a new file or folder
+	 *
+	 * @param string $file
+	 * @param array $data
+	 *
+	 * @return int file id
+	 * @throws \RuntimeException
+	 * @since 9.0.0
+	 */
+	public function insert($file, array $data);
+
+	/**
+	 * update the metadata of an existing file or folder in the cache
+	 *
+	 * @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
+	 * @since 9.0.0
+	 */
+	public function update($id, array $data);
+
+	/**
+	 * 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
+	 * @since 9.0.0
+	 */
+	public function getId($file);
+
+	/**
+	 * get the id of the parent folder of a file
+	 *
+	 * @param string $file
+	 * @return int
+	 * @since 9.0.0
+	 */
+	public function getParentId($file);
+
+	/**
+	 * check if a file is available in the cache
+	 *
+	 * @param string $file
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function inCache($file);
+
+	/**
+	 * 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
+	 * @since 9.0.0
+	 */
+	public function remove($file);
+
+	/**
+	 * Move a file or folder in the cache
+	 *
+	 * @param string $source
+	 * @param string $target
+	 * @since 9.0.0
+	 */
+	public function move($source, $target);
+
+	/**
+	 * Move a file or folder in the cache
+	 *
+	 * Note that this should make sure the entries are removed from the source cache
+	 *
+	 * @param \OCP\Files\Cache\ICache $sourceCache
+	 * @param string $sourcePath
+	 * @param string $targetPath
+	 * @throws \OC\DatabaseException
+	 * @since 9.0.0
+	 */
+	public function moveFromCache(ICache $sourceCache, $sourcePath, $targetPath);
+
+	/**
+	 * Get the scan status of a file
+	 *
+	 * - ICache::NOT_FOUND: File is not in the cache
+	 * - ICache::PARTIAL: File is not stored in the cache but some incomplete data is known
+	 * - ICache::SHALLOW: The folder and it's direct children are in the cache but not all sub folders are fully scanned
+	 * - ICache::COMPLETE: The file or folder, with all it's children) are fully scanned
+	 *
+	 * @param string $file
+	 *
+	 * @return int ICache::NOT_FOUND, ICache::PARTIAL, ICache::SHALLOW or ICache::COMPLETE
+	 * @since 9.0.0
+	 */
+	public function getStatus($file);
+
+	/**
+	 * search for files matching $pattern, files are matched if their filename matches the search pattern
+	 *
+	 * @param string $pattern the search pattern using SQL search syntax (e.g. '%searchstring%')
+	 * @return ICacheEntry[] an array of cache entries where the name matches the search pattern
+	 * @since 9.0.0
+	 * @deprecated 9.0.0 due to lack of pagination, not all backends might implement this
+	 */
+	public function search($pattern);
+
+	/**
+	 * search for files by mimetype
+	 *
+	 * @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 ICacheEntry[] an array of cache entries where the mimetype matches the search
+	 * @since 9.0.0
+	 * @deprecated 9.0.0 due to lack of pagination, not all backends might implement this
+	 */
+	public function searchByMime($mimetype);
+
+	/**
+	 * Search for files by tag of a given users.
+	 *
+	 * Note that every user can tag files differently.
+	 *
+	 * @param string|int $tag name or tag id
+	 * @param string $userId owner of the tags
+	 * @return ICacheEntry[] file data
+	 * @since 9.0.0
+	 * @deprecated 9.0.0 due to lack of pagination, not all backends might implement this
+	 */
+	public function searchByTag($tag, $userId);
+
+	/**
+	 * find a folder in the cache which has not been fully scanned
+	 *
+	 * If multiple incomplete folders are in the cache, the one with the highest id will be returned,
+	 * use the one with the highest id gives the best result with the background scanner, since that is most
+	 * likely the folder where we stopped scanning previously
+	 *
+	 * @return string|bool the path of the folder or false when no folder matched
+	 * @since 9.0.0
+	 */
+	public function getIncomplete();
+
+	/**
+	 * get the path of a file on this storage by it's file id
+	 *
+	 * @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
+	 * @since 9.0.0
+	 */
+	public function getPathById($id);
+
+	/**
+	 * normalize the given path for usage in the cache
+	 *
+	 * @param string $path
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function normalize($path);
+}
diff --git a/lib/public/Files/Cache/ICacheEntry.php b/lib/public/Files/Cache/ICacheEntry.php
new file mode 100644
index 00000000000..00c8e201b9a
--- /dev/null
+++ b/lib/public/Files/Cache/ICacheEntry.php
@@ -0,0 +1,134 @@
+<?php
+/**
+ * @author Robin Appelman <icewind@owncloud.com>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+namespace OCP\Files\Cache;
+
+/**
+ * meta data for a file or folder
+ *
+ * @since 9.0.0
+ */
+interface ICacheEntry {
+	const DIRECTORY_MIMETYPE = 'httpd/unix-directory';
+
+	/**
+	 * Get the numeric id of a file
+	 *
+	 * @return int
+	 * @since 9.0.0
+	 */
+	public function getId();
+
+	/**
+	 * Get the numeric id for the storage
+	 *
+	 * @return int
+	 * @since 9.0.0
+	 */
+	public function getStorageId();
+
+	/**
+	 * Get the path of the file relative to the storage root
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getPath();
+
+	/**
+	 * Get the file name
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getName();
+
+	/**
+	 * Get the full mimetype
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getMimeType();
+
+	/**
+	 * Get the first part of the mimetype
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getMimePart();
+
+	/**
+	 * Get the file size in bytes
+	 *
+	 * @return int
+	 * @since 9.0.0
+	 */
+	public function getSize();
+
+	/**
+	 * Get the last modified date as unix timestamp
+	 *
+	 * @return int
+	 * @since 9.0.0
+	 */
+	public function getMTime();
+
+	/**
+	 * Get the last modified date on the storage as unix timestamp
+	 *
+	 * 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
+	 *
+	 * @return int
+	 * @since 9.0.0
+	 */
+	public function getStorageMTime();
+
+	/**
+	 * Get 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
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getEtag();
+
+	/**
+	 * Get 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
+	 *
+	 * @return int
+	 * @since 9.0.0
+	 */
+	public function getPermissions();
+
+	/**
+	 * Check if the file is encrypted
+	 *
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function isEncrypted();
+}
diff --git a/lib/public/Files/Cache/IPropagator.php b/lib/public/Files/Cache/IPropagator.php
new file mode 100644
index 00000000000..5494ec9a54e
--- /dev/null
+++ b/lib/public/Files/Cache/IPropagator.php
@@ -0,0 +1,36 @@
+<?php
+/**
+ * @author Robin Appelman <icewind@owncloud.com>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+namespace OCP\Files\Cache;
+
+/**
+ * Propagate etags and mtimes within the storage
+ *
+ * @since 9.0.0
+ */
+interface IPropagator {
+	/**
+	 * @param string $internalPath
+	 * @param int $time
+	 * @since 9.0.0
+	 */
+	public function propagateChange($internalPath, $time);
+}
diff --git a/lib/public/Files/Cache/IScanner.php b/lib/public/Files/Cache/IScanner.php
new file mode 100644
index 00000000000..ce1f408028c
--- /dev/null
+++ b/lib/public/Files/Cache/IScanner.php
@@ -0,0 +1,81 @@
+<?php
+/**
+ * @author Robin Appelman <icewind@owncloud.com>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+namespace OCP\Files\Cache;
+
+/**
+ * Scan files from the storage and save to the cache
+ *
+ * @since 9.0.0
+ */
+interface IScanner {
+	const SCAN_RECURSIVE = true;
+	const SCAN_SHALLOW = false;
+
+	const REUSE_ETAG = 1;
+	const REUSE_SIZE = 2;
+
+	/**
+	 * scan a single file and store it in the cache
+	 *
+	 * @param string $file
+	 * @param int $reuseExisting
+	 * @param int $parentId
+	 * @param array | null $cacheData existing data in the cache for the file to be scanned
+	 * @param bool $lock set to false to disable getting an additional read lock during scanning
+	 * @return array an array of metadata of the scanned file
+	 * @throws \OC\ServerNotAvailableException
+	 * @throws \OCP\Lock\LockedException
+	 * @since 9.0.0
+	 */
+	public function scanFile($file, $reuseExisting = 0, $parentId = -1, $cacheData = null, $lock = true);
+
+	/**
+	 * scan a folder and all its children
+	 *
+	 * @param string $path
+	 * @param bool $recursive
+	 * @param int $reuse
+	 * @param bool $lock set to false to disable getting an additional read lock during scanning
+	 * @return array an array of the meta data of the scanned file or folder
+	 * @since 9.0.0
+	 */
+	public function scan($path, $recursive = self::SCAN_RECURSIVE, $reuse = -1, $lock = true);
+
+	/**
+	 * check if the file should be ignored when scanning
+	 * NOTE: files with a '.part' extension are ignored as well!
+	 *       prevents unfinished put requests to be scanned
+	 *
+	 * @param string $file
+	 * @return boolean
+	 * @since 9.0.0
+	 */
+	public static function isPartialFile($file);
+
+	/**
+	 * walk over any folders that are not fully scanned yet and scan them
+	 *
+	 * @since 9.0.0
+	 */
+	public function backgroundScan();
+}
+
diff --git a/lib/public/Files/Cache/IUpdater.php b/lib/public/Files/Cache/IUpdater.php
new file mode 100644
index 00000000000..5267aa6f023
--- /dev/null
+++ b/lib/public/Files/Cache/IUpdater.php
@@ -0,0 +1,75 @@
+<?php
+/**
+ * @author Robin Appelman <icewind@owncloud.com>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+namespace OCP\Files\Cache;
+
+use OCP\Files\Storage\IStorage;
+
+/**
+ * Update the cache and propagate changes
+ *
+ * @since 9.0.0
+ */
+interface IUpdater {
+	/**
+	 * Get the propagator for etags and mtime for the view the updater works on
+	 *
+	 * @return IPropagator
+	 * @since 9.0.0
+	 */
+	public function getPropagator();
+
+	/**
+	 * 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
+	 * @since 9.0.0
+	 */
+	public function propagate($path, $time = null);
+
+	/**
+	 * Update the cache for $path and update the size, etag and mtime of the parent folders
+	 *
+	 * @param string $path
+	 * @param int $time
+	 * @since 9.0.0
+	 */
+	public function update($path, $time = null);
+
+	/**
+	 * Remove $path from the cache and update the size, etag and mtime of the parent folders
+	 *
+	 * @param string $path
+	 * @since 9.0.0
+	 */
+	public function remove($path);
+
+	/**
+	 * Rename a file or folder in the cache and update the size, etag and mtime of the parent folders
+	 *
+	 * @param IStorage $sourceStorage
+	 * @param string $source
+	 * @param string $target
+	 * @since 9.0.0
+	 */
+	public function renameFromStorage(IStorage $sourceStorage, $source, $target);
+}
diff --git a/lib/public/Files/Cache/IWatcher.php b/lib/public/Files/Cache/IWatcher.php
new file mode 100644
index 00000000000..c33129a2473
--- /dev/null
+++ b/lib/public/Files/Cache/IWatcher.php
@@ -0,0 +1,82 @@
+<?php
+/**
+ * @author Robin Appelman <icewind@owncloud.com>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+namespace OCP\Files\Cache;
+
+/**
+ * check the storage backends for updates and change the cache accordingly
+ *
+ * @since 9.0.0
+ */
+interface IWatcher {
+	const CHECK_NEVER = 0; // never check the underlying filesystem for updates
+	const CHECK_ONCE = 1; // check the underlying filesystem for updates once every request for each file
+	const CHECK_ALWAYS = 2; // always check the underlying filesystem for updates
+
+	/**
+	 * @param int $policy either IWatcher::CHECK_NEVER, IWatcher::CHECK_ONCE, IWatcher::CHECK_ALWAYS
+	 * @since 9.0.0
+	 */
+	public function setPolicy($policy);
+
+	/**
+	 * @return int either IWatcher::CHECK_NEVER, IWatcher::CHECK_ONCE, IWatcher::CHECK_ALWAYS
+	 * @since 9.0.0
+	 */
+	public function getPolicy();
+
+	/**
+	 * check $path for updates and update if needed
+	 *
+	 * @param string $path
+	 * @param ICacheEntry|null $cachedEntry
+	 * @return boolean true if path was updated
+	 * @since 9.0.0
+	 */
+	public function checkUpdate($path, $cachedEntry = null);
+
+	/**
+	 * Update the cache for changes to $path
+	 *
+	 * @param string $path
+	 * @param ICacheEntry $cachedData
+	 * @since 9.0.0
+	 */
+	public function update($path, $cachedData);
+
+	/**
+	 * Check if the cache for $path needs to be updated
+	 *
+	 * @param string $path
+	 * @param ICacheEntry $cachedData
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function needsUpdate($path, $cachedData);
+
+	/**
+	 * remove deleted files in $path from the cache
+	 *
+	 * @param string $path
+	 * @since 9.0.0
+	 */
+	public function cleanFolder($path);
+}