1 files changed, 369 insertions, 0 deletions
diff --git a/lib/public/FilesMetadata/Model/IFilesMetadata.php b/lib/public/FilesMetadata/Model/IFilesMetadata.php
new file mode 100644
index 00000000000..b7e2648496b
--- /dev/null
+++ b/lib/public/FilesMetadata/Model/IFilesMetadata.php
@@ -0,0 +1,369 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2023 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\FilesMetadata\Model;
+
+use JsonSerializable;
+use OCP\FilesMetadata\Exceptions\FilesMetadataNotFoundException;
+use OCP\FilesMetadata\Exceptions\FilesMetadataTypeException;
+
+/**
+ * Model that represent metadata linked to a specific file.
+ *
+ * Example of json stored in the database
+ * {
+ *   "mymeta": {
+ *     "value": "this is a test",
+ *     "type": "string",
+ *     "etag": "abcd1234",
+ *     "indexed": false,
+ *     "editPermission": 1
+ *   },
+ *   "myapp-anothermeta": {
+ *     "value": 42,
+ *     "type": "int",
+ *     "etag": "0987zyxw",
+ *     "indexed": true,
+ *     "editPermission": 0
+ *   }
+ * }
+ *
+ * @see IMetadataValueWrapper
+ * @since 28.0.0
+ */
+interface IFilesMetadata extends JsonSerializable {
+	/**
+	 * returns the file id linked to this metadata
+	 *
+	 * @return int related file id
+	 * @since 28.0.0
+	 */
+	public function getFileId(): int;
+
+	/**
+	 * returns last time metadata were updated in the database
+	 *
+	 * @return int timestamp
+	 * @since 28.0.0
+	 */
+	public function lastUpdateTimestamp(): int;
+
+	/**
+	 * returns the token known at the time the metadata were extracted from database
+	 *
+	 * @return string token
+	 * @since 28.0.0
+	 */
+	public function getSyncToken(): string;
+
+	/**
+	 * returns all current metadata keys
+	 *
+	 * @return string[] list of keys
+	 * @since 28.0.0
+	 */
+	public function getKeys(): array;
+
+	/**
+	 * returns true if search metadata key exists
+	 *
+	 * @param string $needle metadata key to search
+	 *
+	 * @return bool TRUE if key exist
+	 * @since 28.0.0
+	 */
+	public function hasKey(string $needle): bool;
+
+	/**
+	 * return the list of metadata keys set as indexed
+	 *
+	 * @return string[] list of indexes
+	 * @since 28.0.0
+	 */
+	public function getIndexes(): array;
+
+	/**
+	 * returns true if key exists and is set as indexed
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return bool
+	 * @since 28.0.0
+	 */
+	public function isIndex(string $key): bool;
+
+	/**
+	 * returns file etag stored during the last update of the metadata key
+	 *
+	 * @param string $key metadata key
+	 * @return string
+	 * @since 29.0.0
+	 */
+	public function getEtag(string $key): string;
+
+	/**
+	 * set file etag
+	 *
+	 * @param string $key metadata key
+	 * @since 29.0.0
+	 */
+	public function setEtag(string $key, string $etag): void;
+
+	/**
+	 * set remote edit permission
+	 * (Webdav PROPPATCH)
+	 *
+	 * @param string $key metadata key
+	 * @param int $permission remote edit permission
+	 *
+	 * @since 28.0.0
+	 */
+	public function setEditPermission(string $key, int $permission): void;
+
+	/**
+	 * returns remote edit permission
+	 * (Webdav PROPPATCH)
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return int
+	 * @since 28.0.0
+	 */
+	public function getEditPermission(string $key): int;
+
+	/**
+	 * returns string value for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return string metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getString(string $key): string;
+
+	/**
+	 * returns int value for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return int metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getInt(string $key): int;
+
+	/**
+	 * returns float value for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return float metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getFloat(string $key): float;
+
+	/**
+	 * returns bool value for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return bool metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getBool(string $key): bool;
+
+	/**
+	 * returns array for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return array metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getArray(string $key): array;
+
+	/**
+	 * returns string[] value for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return string[] metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getStringList(string $key): array;
+
+	/**
+	 * returns int[] value for a metadata key
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return int[] metadata value
+	 * @throws FilesMetadataNotFoundException
+	 * @throws FilesMetadataTypeException
+	 * @since 28.0.0
+	 */
+	public function getIntList(string $key): array;
+
+	/**
+	 * returns the value type of the metadata (string, int, ...)
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return string value type
+	 * @throws FilesMetadataNotFoundException
+	 * @see IMetadataValueWrapper::TYPE_STRING
+	 * @see IMetadataValueWrapper::TYPE_INT
+	 * @see IMetadataValueWrapper::TYPE_FLOAT
+	 * @see IMetadataValueWrapper::TYPE_BOOL
+	 * @see IMetadataValueWrapper::TYPE_ARRAY
+	 * @see IMetadataValueWrapper::TYPE_STRING_LIST
+	 * @see IMetadataValueWrapper::TYPE_INT_LIST
+	 * @since 28.0.0
+	 */
+	public function getType(string $key): string;
+
+	/**
+	 * set a metadata key/value pair for string value
+	 *
+	 * @param string $key metadata key
+	 * @param string $value metadata value
+	 * @param bool $index set TRUE if value must be indexed
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setString(string $key, string $value, bool $index = false): self;
+
+	/**
+	 * set a metadata key/value pair for int value
+	 *
+	 * @param string $key metadata key
+	 * @param int $value metadata value
+	 * @param bool $index set TRUE if value must be indexed
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setInt(string $key, int $value, bool $index = false): self;
+
+	/**
+	 * set a metadata key/value pair for float value
+	 *
+	 * @param string $key metadata key
+	 * @param float $value metadata value
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setFloat(string $key, float $value): self;
+
+	/**
+	 * set a metadata key/value pair for bool value
+	 *
+	 * @param string $key metadata key
+	 * @param bool $value metadata value
+	 * @param bool $index set TRUE if value must be indexed
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setBool(string $key, bool $value, bool $index = false): self;
+
+	/**
+	 * set a metadata key/value pair for array
+	 *
+	 * @param string $key metadata key
+	 * @param array $value metadata value
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setArray(string $key, array $value): self;
+
+	/**
+	 * set a metadata key/value pair for list of string
+	 *
+	 * @param string $key metadata key
+	 * @param string[] $value metadata value
+	 * @param bool $index set TRUE if each values from the list must be indexed
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setStringList(string $key, array $value, bool $index = false): self;
+
+	/**
+	 * set a metadata key/value pair for list of int
+	 *
+	 * @param string $key metadata key
+	 * @param int[] $value metadata value
+	 * @param bool $index set TRUE if each values from the list must be indexed
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function setIntList(string $key, array $value, bool $index = false): self;
+
+	/**
+	 * unset a metadata
+	 *
+	 * @param string $key metadata key
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function unset(string $key): self;
+
+	/**
+	 * unset metadata with key starting with prefix
+	 *
+	 * @param string $keyPrefix metadata key prefix
+	 *
+	 * @return self
+	 * @since 28.0.0
+	 */
+	public function removeStartsWith(string $keyPrefix): self;
+
+	/**
+	 * returns true if object have been updated since last import
+	 *
+	 * @return bool TRUE if metadata have been modified
+	 * @since 28.0.0
+	 */
+	public function updated(): bool;
+
+	/**
+	 * returns metadata in a simple array with METADATA_KEY => METADATA_VALUE
+	 *
+	 * @return array metadata
+	 * @since 28.0.0
+	 */
+	public function asArray(): array;
+
+	/**
+	 * deserialize the object from a json
+	 *
+	 * @param array $data serialized version of the object
+	 *
+	 * @return self
+	 * @see jsonSerialize
+	 * @since 28.0.0
+	 */
+	public function import(array $data): self;
+}