1
0

ICache.php 8.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268
  1. <?php
  2. /**
  3. * @copyright Copyright (c) 2016, ownCloud, Inc.
  4. *
  5. * @author Robin Appelman <robin@icewind.nl>
  6. *
  7. * @license AGPL-3.0
  8. *
  9. * This code is free software: you can redistribute it and/or modify
  10. * it under the terms of the GNU Affero General Public License, version 3,
  11. * as published by the Free Software Foundation.
  12. *
  13. * This program is distributed in the hope that it will be useful,
  14. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16. * GNU Affero General Public License for more details.
  17. *
  18. * You should have received a copy of the GNU Affero General Public License, version 3,
  19. * along with this program. If not, see <http://www.gnu.org/licenses/>
  20. *
  21. */
  22. namespace OCP\Files\Cache;
  23. use OCP\Files\Search\ISearchQuery;
  24. /**
  25. * Metadata cache for a storage
  26. *
  27. * The cache stores the metadata for all files and folders in a storage and is kept up to date trough the following mechanisms:
  28. *
  29. * - Scanner: scans the storage and updates the cache where needed
  30. * - Watcher: checks for changes made to the filesystem outside of the ownCloud instance and rescans files and folder when a change is detected
  31. * - Updater: listens to changes made to the filesystem inside of the ownCloud instance and updates the cache where needed
  32. * - ChangePropagator: updates the mtime and etags of parent folders whenever a change to the cache is made to the cache by the updater
  33. *
  34. * @since 9.0.0
  35. */
  36. interface ICache {
  37. const NOT_FOUND = 0;
  38. const PARTIAL = 1; //only partial data available, file not cached in the database
  39. const SHALLOW = 2; //folder in cache, but not all child files are completely scanned
  40. const COMPLETE = 3;
  41. /**
  42. * Get the numeric storage id for this cache's storage
  43. *
  44. * @return int
  45. * @since 9.0.0
  46. */
  47. public function getNumericStorageId();
  48. /**
  49. * get the stored metadata of a file or folder
  50. *
  51. * @param string | int $file either the path of a file or folder or the file id for a file or folder
  52. * @return ICacheEntry|false the cache entry or false if the file is not found in the cache
  53. * @since 9.0.0
  54. */
  55. public function get($file);
  56. /**
  57. * get the metadata of all files stored in $folder
  58. *
  59. * Only returns files one level deep, no recursion
  60. *
  61. * @param string $folder
  62. * @return ICacheEntry[]
  63. * @since 9.0.0
  64. */
  65. public function getFolderContents($folder);
  66. /**
  67. * get the metadata of all files stored in $folder
  68. *
  69. * Only returns files one level deep, no recursion
  70. *
  71. * @param int $fileId the file id of the folder
  72. * @return ICacheEntry[]
  73. * @since 9.0.0
  74. */
  75. public function getFolderContentsById($fileId);
  76. /**
  77. * store meta data for a file or folder
  78. * This will automatically call either insert or update depending on if the file exists
  79. *
  80. * @param string $file
  81. * @param array $data
  82. *
  83. * @return int file id
  84. * @throws \RuntimeException
  85. * @since 9.0.0
  86. */
  87. public function put($file, array $data);
  88. /**
  89. * insert meta data for a new file or folder
  90. *
  91. * @param string $file
  92. * @param array $data
  93. *
  94. * @return int file id
  95. * @throws \RuntimeException
  96. * @since 9.0.0
  97. */
  98. public function insert($file, array $data);
  99. /**
  100. * update the metadata of an existing file or folder in the cache
  101. *
  102. * @param int $id the fileid of the existing file or folder
  103. * @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
  104. * @since 9.0.0
  105. */
  106. public function update($id, array $data);
  107. /**
  108. * get the file id for a file
  109. *
  110. * 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
  111. *
  112. * File ids are easiest way for apps to store references to a file since unlike paths they are not affected by renames or sharing
  113. *
  114. * @param string $file
  115. * @return int
  116. * @since 9.0.0
  117. */
  118. public function getId($file);
  119. /**
  120. * get the id of the parent folder of a file
  121. *
  122. * @param string $file
  123. * @return int
  124. * @since 9.0.0
  125. */
  126. public function getParentId($file);
  127. /**
  128. * check if a file is available in the cache
  129. *
  130. * @param string $file
  131. * @return bool
  132. * @since 9.0.0
  133. */
  134. public function inCache($file);
  135. /**
  136. * remove a file or folder from the cache
  137. *
  138. * when removing a folder from the cache all files and folders inside the folder will be removed as well
  139. *
  140. * @param string $file
  141. * @since 9.0.0
  142. */
  143. public function remove($file);
  144. /**
  145. * Move a file or folder in the cache
  146. *
  147. * @param string $source
  148. * @param string $target
  149. * @since 9.0.0
  150. */
  151. public function move($source, $target);
  152. /**
  153. * Move a file or folder in the cache
  154. *
  155. * Note that this should make sure the entries are removed from the source cache
  156. *
  157. * @param \OCP\Files\Cache\ICache $sourceCache
  158. * @param string $sourcePath
  159. * @param string $targetPath
  160. * @throws \OC\DatabaseException
  161. * @since 9.0.0
  162. */
  163. public function moveFromCache(ICache $sourceCache, $sourcePath, $targetPath);
  164. /**
  165. * Get the scan status of a file
  166. *
  167. * - ICache::NOT_FOUND: File is not in the cache
  168. * - ICache::PARTIAL: File is not stored in the cache but some incomplete data is known
  169. * - ICache::SHALLOW: The folder and it's direct children are in the cache but not all sub folders are fully scanned
  170. * - ICache::COMPLETE: The file or folder, with all it's children) are fully scanned
  171. *
  172. * @param string $file
  173. *
  174. * @return int ICache::NOT_FOUND, ICache::PARTIAL, ICache::SHALLOW or ICache::COMPLETE
  175. * @since 9.0.0
  176. */
  177. public function getStatus($file);
  178. /**
  179. * search for files matching $pattern, files are matched if their filename matches the search pattern
  180. *
  181. * @param string $pattern the search pattern using SQL search syntax (e.g. '%searchstring%')
  182. * @return ICacheEntry[] an array of cache entries where the name matches the search pattern
  183. * @since 9.0.0
  184. * @deprecated 9.0.0 due to lack of pagination, not all backends might implement this
  185. */
  186. public function search($pattern);
  187. /**
  188. * search for files by mimetype
  189. *
  190. * @param string $mimetype either a full mimetype to search ('text/plain') or only the first part of a mimetype ('image')
  191. * where it will search for all mimetypes in the group ('image/*')
  192. * @return ICacheEntry[] an array of cache entries where the mimetype matches the search
  193. * @since 9.0.0
  194. * @deprecated 9.0.0 due to lack of pagination, not all backends might implement this
  195. */
  196. public function searchByMime($mimetype);
  197. /**
  198. * Search for files with a flexible query
  199. *
  200. * @param ISearchQuery $query
  201. * @return ICacheEntry[]
  202. * @throw \InvalidArgumentException if the cache is unable to perform the query
  203. * @since 12.0.0
  204. */
  205. public function searchQuery(ISearchQuery $query);
  206. /**
  207. * Search for files by tag of a given users.
  208. *
  209. * Note that every user can tag files differently.
  210. *
  211. * @param string|int $tag name or tag id
  212. * @param string $userId owner of the tags
  213. * @return ICacheEntry[] file data
  214. * @since 9.0.0
  215. * @deprecated 9.0.0 due to lack of pagination, not all backends might implement this
  216. */
  217. public function searchByTag($tag, $userId);
  218. /**
  219. * find a folder in the cache which has not been fully scanned
  220. *
  221. * If multiple incomplete folders are in the cache, the one with the highest id will be returned,
  222. * use the one with the highest id gives the best result with the background scanner, since that is most
  223. * likely the folder where we stopped scanning previously
  224. *
  225. * @return string|bool the path of the folder or false when no folder matched
  226. * @since 9.0.0
  227. */
  228. public function getIncomplete();
  229. /**
  230. * get the path of a file on this storage by it's file id
  231. *
  232. * @param int $id the file id of the file or folder to search
  233. * @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
  234. * @since 9.0.0
  235. */
  236. public function getPathById($id);
  237. /**
  238. * normalize the given path for usage in the cache
  239. *
  240. * @param string $path
  241. * @return string
  242. * @since 9.0.0
  243. */
  244. public function normalize($path);
  245. }