add since tags

lib/public/files/cache/icache.php

@@ -30,6 +30,8 @@ namespace OCP\Files\Cache;
  * - 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;
@@ -41,6 +43,7 @@ interface ICache {
 	 * Get the numeric storage id for this cache's storage
 	 *
 	 * @return int
+	 * @since 9.0.0
 	 */
 	public function getNumericStorageId();
 
@@ -49,6 +52,7 @@ interface ICache {
 	 *
 	 * @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);
 
@@ -57,6 +61,7 @@ interface ICache {
 	 *
 	 * @param string $folder
 	 * @return ICacheEntry[]
+	 * @since 9.0.0
 	 */
 	public function getFolderContents($folder);
 
@@ -65,6 +70,7 @@ interface ICache {
 	 *
 	 * @param int $fileId the file id of the folder
 	 * @return ICacheEntry[]
+	 * @since 9.0.0
 	 */
 	public function getFolderContentsById($fileId);
 
@@ -76,6 +82,7 @@ interface ICache {
 	 *
 	 * @return int file id
 	 * @throws \RuntimeException
+	 * @since 9.0.0
 	 */
 	public function put($file, array $data);
 
@@ -84,6 +91,7 @@ interface ICache {
 	 *
 	 * @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);
 
@@ -96,6 +104,7 @@ interface ICache {
 	 *
 	 * @param string $file
 	 * @return int
+	 * @since 9.0.0
 	 */
 	public function getId($file);
 
@@ -104,6 +113,7 @@ interface ICache {
 	 *
 	 * @param string $file
 	 * @return int
+	 * @since 9.0.0
 	 */
 	public function getParentId($file);
 
@@ -112,6 +122,7 @@ interface ICache {
 	 *
 	 * @param string $file
 	 * @return bool
+	 * @since 9.0.0
 	 */
 	public function inCache($file);
 
@@ -121,6 +132,7 @@ interface ICache {
 	 * 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);
 
@@ -129,6 +141,7 @@ interface ICache {
 	 *
 	 * @param string $source
 	 * @param string $target
+	 * @since 9.0.0
 	 */
 	public function move($source, $target);
 
@@ -139,11 +152,14 @@ interface ICache {
 	 * @param string $sourcePath
 	 * @param string $targetPath
 	 * @throws \OC\DatabaseException
+	 * @since 9.0.0
 	 */
 	public function moveFromCache(ICache $sourceCache, $sourcePath, $targetPath);
 
 	/**
 	 * remove all entries for files that are stored on the storage from the cache
+	 *
+	 * @since 9.0.0
 	 */
 	public function clear();
 
@@ -158,6 +174,7 @@ interface ICache {
 	 * @param string $file
 	 *
 	 * @return int ICache::NOT_FOUND, ICache::PARTIAL, ICache::SHALLOW or ICache::COMPLETE
+	 * @since 9.0.0
 	 */
 	public function getStatus($file);
 
@@ -166,6 +183,7 @@ interface ICache {
 	 *
 	 * @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
 	 */
 	public function search($pattern);
 
@@ -175,6 +193,7 @@ interface ICache {
 	 * @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
 	 */
 	public function searchByMime($mimetype);
 
@@ -186,6 +205,7 @@ interface ICache {
 	 * @param string|int $tag name or tag id
 	 * @param string $userId owner of the tags
 	 * @return ICacheEntry[] file data
+	 * @since 9.0.0
 	 */
 	public function searchByTag($tag, $userId);
 
@@ -194,6 +214,7 @@ interface ICache {
 	 *
 	 * @param string|boolean $path
 	 * @param array $data (optional) meta data of the folder
+	 * @since 9.0.0
 	 */
 	public function correctFolderSize($path, $data = null);
 
@@ -203,6 +224,7 @@ interface ICache {
 	 * @param string $path
 	 * @param array $entry (optional) meta data of the folder
 	 * @return int
+	 * @since 9.0.0
 	 */
 	public function calculateFolderSize($path, $entry = null);
 
@@ -210,6 +232,7 @@ interface ICache {
 	 * get all file ids on the files on the storage
 	 *
 	 * @return int[]
+	 * @since 9.0.0
 	 */
 	public function getAll();
 
@@ -221,6 +244,7 @@ interface ICache {
 	 * 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();
 
@@ -229,6 +253,7 @@ interface ICache {
 	 *
 	 * @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);
 
@@ -237,6 +262,7 @@ interface ICache {
 	 *
 	 * @param string $path
 	 * @return string
+	 * @since 9.0.0
 	 */
 	public function normalize($path);
 }

lib/public/files/cache/icacheentry.php

@@ -23,12 +23,15 @@ namespace OCP\Files\Cache;
 
 /**
  * meta data for a file or folder
+ *
+ * @since 9.0.0
  */
 interface ICacheEntry {
 	/**
 	 * Get the numeric id of a file
 	 *
 	 * @return int
+	 * @since 9.0.0
 	 */
 	public function getId();
 
@@ -36,6 +39,7 @@ interface ICacheEntry {
 	 * Get the numeric id for the storage
 	 *
 	 * @return int
+	 * @since 9.0.0
 	 */
 	public function getStorageId();
 
@@ -43,6 +47,7 @@ interface ICacheEntry {
 	 * Get the path of the file relative to the storage root
 	 *
 	 * @return string
+	 * @since 9.0.0
 	 */
 	public function getPath();
 
@@ -50,6 +55,7 @@ interface ICacheEntry {
 	 * Get the file name
 	 *
 	 * @return string
+	 * @since 9.0.0
 	 */
 	public function getName();
 
@@ -57,6 +63,7 @@ interface ICacheEntry {
 	 * Get the full mimetype
 	 *
 	 * @return string
+	 * @since 9.0.0
 	 */
 	public function getMimeType();
 
@@ -64,6 +71,7 @@ interface ICacheEntry {
 	 * Get the first part of the mimetype
 	 *
 	 * @return string
+	 * @since 9.0.0
 	 */
 	public function getMimePart();
 
@@ -71,6 +79,7 @@ interface ICacheEntry {
 	 * Get the file size in bytes
 	 *
 	 * @return int
+	 * @since 9.0.0
 	 */
 	public function getSize();
 
@@ -78,6 +87,7 @@ interface ICacheEntry {
 	 * Get the last modified date as unix timestamp
 	 *
 	 * @return int
+	 * @since 9.0.0
 	 */
 	public function getMTime();
 
@@ -88,6 +98,7 @@ interface ICacheEntry {
 	 * 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();
 
@@ -98,6 +109,7 @@ interface ICacheEntry {
 	 * Etag for folders change whenever a file in the folder has changed
 	 *
 	 * @return string
+	 * @since 9.0.0
 	 */
 	public function getEtag();
 
@@ -106,6 +118,7 @@ interface ICacheEntry {
 	 * \OCP\PERMISSION_UPDATE, \OCP\PERMISSION_DELETE and \OCP\PERMISSION_SHARE
 	 *
 	 * @return int
+	 * @since 9.0.0
 	 */
 	public function getPermissions();
 
@@ -113,6 +126,7 @@ interface ICacheEntry {
 	 * Check if the file is encrypted
 	 *
 	 * @return bool
+	 * @since 9.0.0
 	 */
 	public function isEncrypted();
 }

lib/public/files/cache/ipropagator.php

@@ -23,12 +23,15 @@ namespace OCP\Files\Cache;
 
 /**
  * Propagate etags and mtimes within the storage
+ *
+ * @since 9.0.0
  */
 interface IPropagator {
 	/**
 	 * @param string $internalPath
 	 * @param int $time
 	 * @return array[] all propagated cache entries
+	 * @since 9.0.0
 	 */
 	public function propagateChange($internalPath, $time);
 }

lib/public/files/cache/iscanner.php

@@ -23,6 +23,8 @@ namespace OCP\Files\Cache;
 
 /**
  * Scan files form the storage and save to the cache
+ *
+ * @since 9.0.0
  */
 interface IScanner {
 	const SCAN_RECURSIVE = true;
@@ -42,6 +44,7 @@ interface IScanner {
 	 * @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);
 
@@ -53,6 +56,7 @@ interface IScanner {
 	 * @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);
 
@@ -63,11 +67,14 @@ interface IScanner {
 	 *
 	 * @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();
 }

lib/public/files/cache/iupdater.php

@@ -25,12 +25,14 @@ use OCP\Files\Storage;
 /**
  * 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();
 
@@ -39,6 +41,7 @@ interface IUpdater {
 	 *
 	 * @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);
 
@@ -47,6 +50,7 @@ interface IUpdater {
 	 *
 	 * @param string $path
 	 * @param int $time
+	 * @since 9.0.0
 	 */
 	public function update($path, $time = null);
 
@@ -54,6 +58,7 @@ interface IUpdater {
 	 * 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);
 
@@ -63,6 +68,7 @@ interface IUpdater {
 	 * @param \OCP\Files\Storage $sourceStorage
 	 * @param string $source
 	 * @param string $target
+	 * @since 9.0.0
 	 */
 	public function renameFromStorage(Storage $sourceStorage, $source, $target);
 }

lib/public/files/cache/iwatcher.php

@@ -23,6 +23,8 @@ 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
@@ -31,11 +33,13 @@ interface IWatcher {
 
 	/**
 	 * @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();
 
@@ -45,6 +49,7 @@ interface IWatcher {
 	 * @param string $path
 	 * @param ICacheEntry|null $cachedEntry
 	 * @return boolean true if path was updated
+	 * @since 9.0.0
 	 */
 	public function checkUpdate($path, $cachedEntry = null);
 
@@ -53,6 +58,7 @@ interface IWatcher {
 	 *
 	 * @param string $path
 	 * @param ICacheEntry $cachedData
+	 * @since 9.0.0
 	 */
 	public function update($path, $cachedData);
 
@@ -62,6 +68,7 @@ interface IWatcher {
 	 * @param string $path
 	 * @param ICacheEntry $cachedData
 	 * @return bool
+	 * @since 9.0.0
 	 */
 	public function needsUpdate($path, $cachedData);
 
@@ -69,6 +76,7 @@ interface IWatcher {
 	 * remove deleted files in $path from the cache
 	 *
 	 * @param string $path
+	 * @since 9.0.0
 	 */
 	public function cleanFolder($path);
 }

lib/public/files/storage.php

@@ -476,26 +476,31 @@ interface Storage {
 
 	/**
 	 * @return ICache
+	 * @since 9.0.0
 	 */
 	public function getCache();
 
 	/**
 	 * @return IPropagator
+	 * @since 9.0.0
 	 */
 	public function getPropagator();
 
 	/**
 	 * @return IScanner
+	 * @since 9.0.0
 	 */
 	public function getScanner();
 
 	/**
 	 * @return IUpdater
+	 * @since 9.0.0
 	 */
 	public function getUpdater();
 
 	/**
 	 * @return IWatcher
+	 * @since 9.0.0
 	 */
 	public function getWatcher();
 }