IFilesMetadata.php 8.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
  5. * SPDX-License-Identifier: AGPL-3.0-or-later
  6. */
  7. namespace OCP\FilesMetadata\Model;
  8. use JsonSerializable;
  9. use OCP\FilesMetadata\Exceptions\FilesMetadataNotFoundException;
  10. use OCP\FilesMetadata\Exceptions\FilesMetadataTypeException;
  11. /**
  12. * Model that represent metadata linked to a specific file.
  13. *
  14. * Example of json stored in the database
  15. * {
  16. * "mymeta": {
  17. * "value": "this is a test",
  18. * "type": "string",
  19. * "etag": "abcd1234",
  20. * "indexed": false,
  21. * "editPermission": 1
  22. * },
  23. * "myapp-anothermeta": {
  24. * "value": 42,
  25. * "type": "int",
  26. * "etag": "0987zyxw",
  27. * "indexed": true,
  28. * "editPermission": 0
  29. * }
  30. * }
  31. *
  32. * @see IMetadataValueWrapper
  33. * @since 28.0.0
  34. */
  35. interface IFilesMetadata extends JsonSerializable {
  36. /**
  37. * returns the file id linked to this metadata
  38. *
  39. * @return int related file id
  40. * @since 28.0.0
  41. */
  42. public function getFileId(): int;
  43. /**
  44. * returns last time metadata were updated in the database
  45. *
  46. * @return int timestamp
  47. * @since 28.0.0
  48. */
  49. public function lastUpdateTimestamp(): int;
  50. /**
  51. * returns the token known at the time the metadata were extracted from database
  52. *
  53. * @return string token
  54. * @since 28.0.0
  55. */
  56. public function getSyncToken(): string;
  57. /**
  58. * returns all current metadata keys
  59. *
  60. * @return string[] list of keys
  61. * @since 28.0.0
  62. */
  63. public function getKeys(): array;
  64. /**
  65. * returns true if search metadata key exists
  66. *
  67. * @param string $needle metadata key to search
  68. *
  69. * @return bool TRUE if key exist
  70. * @since 28.0.0
  71. */
  72. public function hasKey(string $needle): bool;
  73. /**
  74. * return the list of metadata keys set as indexed
  75. *
  76. * @return string[] list of indexes
  77. * @since 28.0.0
  78. */
  79. public function getIndexes(): array;
  80. /**
  81. * returns true if key exists and is set as indexed
  82. *
  83. * @param string $key metadata key
  84. *
  85. * @return bool
  86. * @since 28.0.0
  87. */
  88. public function isIndex(string $key): bool;
  89. /**
  90. * returns file etag stored during the last update of the metadata key
  91. *
  92. * @param string $key metadata key
  93. * @return string
  94. * @since 29.0.0
  95. */
  96. public function getEtag(string $key): string;
  97. /**
  98. * set file etag
  99. *
  100. * @param string $key metadata key
  101. * @since 29.0.0
  102. */
  103. public function setEtag(string $key, string $etag): void;
  104. /**
  105. * set remote edit permission
  106. * (Webdav PROPPATCH)
  107. *
  108. * @param string $key metadata key
  109. * @param int $permission remote edit permission
  110. *
  111. * @since 28.0.0
  112. */
  113. public function setEditPermission(string $key, int $permission): void;
  114. /**
  115. * returns remote edit permission
  116. * (Webdav PROPPATCH)
  117. *
  118. * @param string $key metadata key
  119. *
  120. * @return int
  121. * @since 28.0.0
  122. */
  123. public function getEditPermission(string $key): int;
  124. /**
  125. * returns string value for a metadata key
  126. *
  127. * @param string $key metadata key
  128. *
  129. * @return string metadata value
  130. * @throws FilesMetadataNotFoundException
  131. * @throws FilesMetadataTypeException
  132. * @since 28.0.0
  133. */
  134. public function getString(string $key): string;
  135. /**
  136. * returns int value for a metadata key
  137. *
  138. * @param string $key metadata key
  139. *
  140. * @return int metadata value
  141. * @throws FilesMetadataNotFoundException
  142. * @throws FilesMetadataTypeException
  143. * @since 28.0.0
  144. */
  145. public function getInt(string $key): int;
  146. /**
  147. * returns float value for a metadata key
  148. *
  149. * @param string $key metadata key
  150. *
  151. * @return float metadata value
  152. * @throws FilesMetadataNotFoundException
  153. * @throws FilesMetadataTypeException
  154. * @since 28.0.0
  155. */
  156. public function getFloat(string $key): float;
  157. /**
  158. * returns bool value for a metadata key
  159. *
  160. * @param string $key metadata key
  161. *
  162. * @return bool metadata value
  163. * @throws FilesMetadataNotFoundException
  164. * @throws FilesMetadataTypeException
  165. * @since 28.0.0
  166. */
  167. public function getBool(string $key): bool;
  168. /**
  169. * returns array for a metadata key
  170. *
  171. * @param string $key metadata key
  172. *
  173. * @return array metadata value
  174. * @throws FilesMetadataNotFoundException
  175. * @throws FilesMetadataTypeException
  176. * @since 28.0.0
  177. */
  178. public function getArray(string $key): array;
  179. /**
  180. * returns string[] value for a metadata key
  181. *
  182. * @param string $key metadata key
  183. *
  184. * @return string[] metadata value
  185. * @throws FilesMetadataNotFoundException
  186. * @throws FilesMetadataTypeException
  187. * @since 28.0.0
  188. */
  189. public function getStringList(string $key): array;
  190. /**
  191. * returns int[] value for a metadata key
  192. *
  193. * @param string $key metadata key
  194. *
  195. * @return int[] metadata value
  196. * @throws FilesMetadataNotFoundException
  197. * @throws FilesMetadataTypeException
  198. * @since 28.0.0
  199. */
  200. public function getIntList(string $key): array;
  201. /**
  202. * returns the value type of the metadata (string, int, ...)
  203. *
  204. * @param string $key metadata key
  205. *
  206. * @return string value type
  207. * @throws FilesMetadataNotFoundException
  208. * @see IMetadataValueWrapper::TYPE_STRING
  209. * @see IMetadataValueWrapper::TYPE_INT
  210. * @see IMetadataValueWrapper::TYPE_FLOAT
  211. * @see IMetadataValueWrapper::TYPE_BOOL
  212. * @see IMetadataValueWrapper::TYPE_ARRAY
  213. * @see IMetadataValueWrapper::TYPE_STRING_LIST
  214. * @see IMetadataValueWrapper::TYPE_INT_LIST
  215. * @since 28.0.0
  216. */
  217. public function getType(string $key): string;
  218. /**
  219. * set a metadata key/value pair for string value
  220. *
  221. * @param string $key metadata key
  222. * @param string $value metadata value
  223. * @param bool $index set TRUE if value must be indexed
  224. *
  225. * @return self
  226. * @since 28.0.0
  227. */
  228. public function setString(string $key, string $value, bool $index = false): self;
  229. /**
  230. * set a metadata key/value pair for int value
  231. *
  232. * @param string $key metadata key
  233. * @param int $value metadata value
  234. * @param bool $index set TRUE if value must be indexed
  235. *
  236. * @return self
  237. * @since 28.0.0
  238. */
  239. public function setInt(string $key, int $value, bool $index = false): self;
  240. /**
  241. * set a metadata key/value pair for float value
  242. *
  243. * @param string $key metadata key
  244. * @param float $value metadata value
  245. *
  246. * @return self
  247. * @since 28.0.0
  248. */
  249. public function setFloat(string $key, float $value): self;
  250. /**
  251. * set a metadata key/value pair for bool value
  252. *
  253. * @param string $key metadata key
  254. * @param bool $value metadata value
  255. * @param bool $index set TRUE if value must be indexed
  256. *
  257. * @return self
  258. * @since 28.0.0
  259. */
  260. public function setBool(string $key, bool $value, bool $index = false): self;
  261. /**
  262. * set a metadata key/value pair for array
  263. *
  264. * @param string $key metadata key
  265. * @param array $value metadata value
  266. *
  267. * @return self
  268. * @since 28.0.0
  269. */
  270. public function setArray(string $key, array $value): self;
  271. /**
  272. * set a metadata key/value pair for list of string
  273. *
  274. * @param string $key metadata key
  275. * @param string[] $value metadata value
  276. * @param bool $index set TRUE if each values from the list must be indexed
  277. *
  278. * @return self
  279. * @since 28.0.0
  280. */
  281. public function setStringList(string $key, array $value, bool $index = false): self;
  282. /**
  283. * set a metadata key/value pair for list of int
  284. *
  285. * @param string $key metadata key
  286. * @param int[] $value metadata value
  287. * @param bool $index set TRUE if each values from the list must be indexed
  288. *
  289. * @return self
  290. * @since 28.0.0
  291. */
  292. public function setIntList(string $key, array $value, bool $index = false): self;
  293. /**
  294. * unset a metadata
  295. *
  296. * @param string $key metadata key
  297. *
  298. * @return self
  299. * @since 28.0.0
  300. */
  301. public function unset(string $key): self;
  302. /**
  303. * unset metadata with key starting with prefix
  304. *
  305. * @param string $keyPrefix metadata key prefix
  306. *
  307. * @return self
  308. * @since 28.0.0
  309. */
  310. public function removeStartsWith(string $keyPrefix): self;
  311. /**
  312. * returns true if object have been updated since last import
  313. *
  314. * @return bool TRUE if metadata have been modified
  315. * @since 28.0.0
  316. */
  317. public function updated(): bool;
  318. /**
  319. * returns metadata in a simple array with METADATA_KEY => METADATA_VALUE
  320. *
  321. * @return array metadata
  322. * @since 28.0.0
  323. */
  324. public function asArray(): array;
  325. /**
  326. * deserialize the object from a json
  327. *
  328. * @param array $data serialized version of the object
  329. *
  330. * @return self
  331. * @see jsonSerialize
  332. * @since 28.0.0
  333. */
  334. public function import(array $data): self;
  335. }