1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
<?php
declare(strict_types=1);
/**
* @copyright 2023 Maxence Lange <maxence@artificial-owl.com>
*
* @author Maxence Lange <maxence@artificial-owl.com>
*
* @license GNU AGPL version 3 or any later version
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* 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
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
*/
namespace OCP\FilesMetadata;
use OCP\DB\QueryBuilder\IQueryBuilder;
use OCP\Files\Node;
use OCP\FilesMetadata\Exceptions\FilesMetadataException;
use OCP\FilesMetadata\Exceptions\FilesMetadataNotFoundException;
use OCP\FilesMetadata\Model\IFilesMetadata;
use OCP\FilesMetadata\Model\IMetadataValueWrapper;
/**
* Manager for FilesMetadata; manage files' metadata.
*
* @since 28.0.0
*/
interface IFilesMetadataManager {
/** @since 28.0.0 */
public const PROCESS_LIVE = 1;
/** @since 28.0.0 */
public const PROCESS_BACKGROUND = 2;
/** @since 28.0.0 */
public const PROCESS_NAMED = 4;
/**
* initiate the process of refreshing the metadata in relation to a node
* usually, this process:
* - get current metadata from database, if available, or create a new one
* - dispatch a MetadataLiveEvent,
* - save new metadata in database, if metadata have been changed during the event
* - refresh metadata indexes if needed,
* - prep a new cronjob if an app request it during the event,
*
* @param Node $node related node
* @param int $process type of process
* @param string $namedEvent limit process to a named event
*
* @return IFilesMetadata
* @see self::PROCESS_BACKGROUND
* @see self::PROCESS_LIVE
* @see self::PROCESS_NAMED
* @since 28.0.0
*/
public function refreshMetadata(
Node $node,
int $process = self::PROCESS_LIVE,
string $namedEvent = ''
): IFilesMetadata;
/**
* returns metadata of a file id
*
* @param int $fileId file id
* @param boolean $generate Generate if metadata does not exist
*
* @return IFilesMetadata
* @throws FilesMetadataNotFoundException if not found
* @since 28.0.0
*/
public function getMetadata(int $fileId, bool $generate = false): IFilesMetadata;
/**
* returns metadata of multiple file ids
*
* @param int[] $fileIds file ids
*
* @return array File ID is the array key, files without metadata are not returned in the array
* @psalm-return array<int, IFilesMetadata>
* @since 28.0.0
*/
public function getMetadataForFiles(array $fileIds): array;
/**
* save metadata to database and refresh indexes.
* metadata are saved if new data are available.
* on update, a check on syncToken is done to avoid conflict (race condition)
*
* @param IFilesMetadata $filesMetadata
*
* @throws FilesMetadataException if metadata seems malformed
* @since 28.0.0
*/
public function saveMetadata(IFilesMetadata $filesMetadata): void;
/**
* delete metadata and its indexes
*
* @param int $fileId file id
*
* @return void
* @since 28.0.0
*/
public function deleteMetadata(int $fileId): void;
/**
* generate and return a MetadataQuery to help building sql queries
*
* @param IQueryBuilder $qb
* @param string $fileTableAlias alias of the table that contains data about files
* @param string $fileIdField alias of the field that contains file ids
*
* @return IMetadataQuery|null NULL if table are not set yet or never used
* @see IMetadataQuery
* @since 28.0.0
*/
public function getMetadataQuery(
IQueryBuilder $qb,
string $fileTableAlias,
string $fileIdField
): ?IMetadataQuery;
/**
* returns all type of metadata currently available.
* The list is stored in a IFilesMetadata with null values but correct type.
*
* @return IFilesMetadata
* @since 28.0.0
*/
public function getKnownMetadata(): IFilesMetadata;
/**
* initiate a metadata key with its type.
* The call is mandatory before using the metadata property in a webdav request.
* It is not needed to only use this method when the app is enabled: the method can be
* called each time during the app loading as the metadata will only be initiated if not known
*
* @param string $key metadata key
* @param string $type metadata type
* @param bool $indexed TRUE if metadata can be search
* @param int $editPermission remote edit permission via Webdav PROPPATCH
*
* @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
* @see IMetadataValueWrapper::TYPE_STRING
* @see IMetadataValueWrapper::EDIT_FORBIDDEN
* @see IMetadataValueWrapper::EDIT_REQ_OWNERSHIP
* @see IMetadataValueWrapper::EDIT_REQ_WRITE_PERMISSION
* @see IMetadataValueWrapper::EDIT_REQ_READ_PERMISSION
* @since 28.0.0
*/
public function initMetadata(string $key, string $type, bool $indexed, int $editPermission): void;
}
|
