1 /*
2 * Licensed to The Apereo Foundation under one or more contributor license
3 * agreements. See the NOTICE file distributed with this work for additional
4 * information regarding copyright ownership.
5 *
6 *
7 * The Apereo Foundation licenses this file to you under the Educational
8 * Community License, Version 2.0 (the "License"); you may not use this file
9 * except in compliance with the License. You may obtain a copy of the License
10 * at:
11 *
12 * http://opensource.org/licenses/ecl2.txt
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
17 * License for the specific language governing permissions and limitations under
18 * the License.
19 *
20 */
21 package org.opencastproject.assetmanager.api;
22
23 import org.opencastproject.assetmanager.api.storage.AssetStore;
24 import org.opencastproject.mediapackage.MediaPackage;
25 import org.opencastproject.security.api.UnauthorizedException;
26 import org.opencastproject.util.NotFoundException;
27
28 import java.util.Collection;
29 import java.util.Date;
30 import java.util.List;
31 import java.util.Optional;
32
33 /**
34 * The AssetManager stores versioned {@linkplain Snapshot snapshots} of media packages.
35 * <p>
36 * It also supports the association of {@linkplain Property properties} to a
37 * history of snapshots which is called an episode.
38 *
39 * <h2>Terms</h2>
40 * <h3>Snapshot</h3>
41 * A snapshot saves a particular version of a media package. Snapshots are
42 * immutable and can only be deleted.
43 *
44 * <h3>Episode</h3>
45 * An episode is the set of snapshots of a media package.
46 *
47 * <h3>Properties</h3>
48 * Properties are associated with an episode and have a volatile character.
49 * They support the quick and easy storage of meta data.
50 * This removes the need for services to create their own persistence layer if
51 * they want to associate metadata with a media package.
52 *
53 * <h2>Notes</h2>
54 * Media package IDs are considered to be unique throughout the whole system.
55 * The organization ID is just a discriminator and not necessary to uniquely identify a media package.
56 */
57 public interface AssetManager {
58 String DEFAULT_OWNER = "default";
59
60 /**
61 * Get the media package from the latest snapshot.
62 *
63 * @param mediaPackageId
64 * @return mediapackage
65 */
66 Optional<MediaPackage> getMediaPackage(String mediaPackageId);
67
68 /**
69 * Get the asset that is uniquely identified by the triple {version, media package ID, media package element ID}.
70 *
71 * @param version the version
72 * @param mpId the media package ID
73 * @param mpeId the media package element ID
74 * @return the asset or none, if no such asset exists
75 */
76 Optional<Asset> getAsset(Version version, String mpId, String mpeId);
77
78 /**
79 * Get an asset store by id (local or remote).
80 *
81 * @param storeId the store id
82 * @return the asset store if it exists
83 */
84 Optional<AssetStore> getAssetStore(String storeId);
85
86 /**
87 * Get the remote asset stores as a list.
88 *
89 * @return a list of asset stores
90 */
91 List<AssetStore> getRemoteAssetStores();
92
93 /**
94 * Get the local asset store.
95 *
96 * @return the asset store
97 */
98 AssetStore getLocalAssetStore();
99
100
101 /* Snapshots */
102
103 /**
104 * Get the latest snapshot.
105 *
106 * @param mediaPackageId
107 * @return Snapshot
108 */
109 Optional<Snapshot> getLatestSnapshot(String mediaPackageId);
110
111 /**
112 * Get the latest snapshots.
113 *
114 * @param mediaPackageIds
115 * @return Snapshot
116 * returns the latest snapshot for each given mediaPackageId
117 */
118 List<Snapshot> getLatestSnapshots(Collection mediaPackageIds);
119
120 /**
121 * Check if any snapshot with the given media package identifier exists.
122 *
123 * @param mediaPackageId
124 * The media package identifier to check for
125 * @return If a snapshot exists for the given media package
126 */
127 boolean snapshotExists(String mediaPackageId);
128
129 /**
130 * Check if any snapshot with the given media package identifier exists.
131 *
132 * @param mediaPackageId
133 * The media package identifier to check for
134 * @param organization
135 * The organization to limit the search to
136 * @return If a snapshot exists for the given media package
137 */
138 boolean snapshotExists(String mediaPackageId, String organization);
139
140 /**
141 * Returns a list of {@link Snapshot} filtered by mediapackage IDs
142 *
143 * @param mpId
144 * The mediapackage ID to filter results for
145 * @return
146 * The {@link Snapshot} list filtered by mediapackage ID
147 */
148 List<Snapshot> getSnapshotsById(String mpId);
149
150 /**
151 * Returns a list of {@link Snapshot}filtered by mediapackage IDs. This stream
152 * consists of all versions of all mediapackage ordered by the Version
153 *
154 * @param mpId
155 * The mediapackage ID to filter results for
156 * @param asc
157 * The asc {@link Boolean} decides if to order ascending (true) or descending (false)
158 * @return
159 * The {@link Snapshot} list filtered by mediapackage ID
160 */
161 List<Snapshot> getSnapshotsByIdOrderedByVersion(String mpId, boolean asc);
162
163 /**
164 * Returns a list of {@link Snapshot} filtered by mediapackage ID and version
165 *
166 * @param mpId
167 * The mediapackage ID to filter results for
168 * @param version
169 * The version to filter results for
170 * @return
171 * The {@link Snapshot} list filtered by mediapackage ID
172 */
173 List<Snapshot> getSnapshotsByIdAndVersion(String mpId, Version version);
174
175 /**
176 * Returns a list of {@link Snapshot} filtered by date. This stream consists of all
177 * a mediapackages which have at least one version archived within the date range.
178 *
179 * @param start
180 * The start {@link Date} to filter by
181 * @param end
182 * The end{@link Date} to filter by
183 * @return
184 * The {@link Snapshot} list filtered by date
185 */
186 List<Snapshot> getSnapshotsByDateOrderedById(Date start, Date end);
187
188 /**
189 * Returns a list of {@link Snapshot} filtered by date and mediapackage. This stream consists of all versions of
190 * a mediapackage archived within the date range.
191 *
192 * @param mpId
193 * The mediapackage ID to filter for
194 * @param start
195 * The start {@link Date} to filter by
196 * @param end
197 * The end{@link Date} to filter by
198 * @return
199 * The {@link Snapshot} list filtered by date
200 */
201 List<Snapshot> getSnapshotsByIdAndDate(String mpId, Date start, Date end);
202
203 /**
204 * Returns a list of {@link Snapshot} filtered by date and mediapackage.
205 * This stream consists of all versions of a mediapackage archived within the
206 * date range ordered by there Version.
207 *
208 * @param mpId
209 * The mediapackage ID to filter for
210 * @param start
211 * The start {@link Date} to filter by
212 * @param end
213 * The end {@link Date} to filter by
214 * @param asc
215 * The asc {@link Boolean} decides if to order ascending (true) or descending (false)
216 * @return
217 * The {@link Snapshot} list filtered by date
218 */
219 List<Snapshot> getSnapshotsByIdAndDateOrderedByVersion(String mpId, Date start, Date end, boolean asc);
220
221 /**
222 * Get the latest snapshots from the series
223 * @param seriesId
224 * the id of the series
225 * @return
226 * a list of the latest snapshots from the series
227 */
228 List<Snapshot> getLatestSnapshotsBySeriesId(String seriesId);
229
230 /**
231 * Gets a snapshot that confirms to the given parameters
232 * @param mpId
233 * the mediaPackageId
234 * @param orgId
235 * the organizationId
236 * @param version
237 * the version
238 * @return
239 */
240 Optional<Snapshot> getSnapshotByMpIdOrgIdAndVersion(String mpId, String orgId, Version version);
241
242 /**
243 * Remove all snapshots with the given mediaPackage id
244 * @param
245 * mpId the mediaPackage id
246 * @return
247 * the amount of snapshots removed
248 */
249 int deleteSnapshots(String mpId);
250
251 /**
252 * Remove all snapshots with the given mediaPackage id, except for the snapshot with the highest version number
253 * @param
254 * mpId the mediaPackage id
255 * @return
256 * the amount of snapshots removed
257 */
258 int deleteAllButLatestSnapshot(String mpId);
259
260 /**
261 * Take a versioned snapshot of a media package.
262 * <p>
263 * Snapshot are tagged with string identifying the owner. Only the owner
264 * of a snapshot is allowed to delete it.
265 * Ownership only affects the deletion of a snapshot.
266 *
267 * @param owner
268 * the owner of the snapshot, e.g. the name of the calling service
269 */
270 Snapshot takeSnapshot(String owner, MediaPackage mp);
271
272 /**
273 * Take a versioned snapshot of a media package using the owner of the last
274 * snapshot or the default owner if it does not exist.
275 *
276 * @param mediaPackage
277 * The media package to snapshot
278 * @return A new snapshot
279 */
280 Snapshot takeSnapshot(MediaPackage mediaPackage);
281
282 /**
283 * Move snapshot from current store to new store
284 * Note: This may require downloading and re-uploading
285 *
286 * @param version The version to move
287 * @param mpId The media package to move
288 * @param storeId The store to move to
289 * @throws NotFoundException
290 */
291 void moveSnapshotToStore(Version version, String mpId, String storeId) throws NotFoundException;
292
293 /**
294 * Moves all versions of a given mediapackage ID from their respective source stores to a single target store
295 * @param mpId
296 * The mediapackage ID to move
297 * @param targetStore
298 * The store ID to move all versions of this mediapackage to
299 * @throws NotFoundException
300 */
301 void moveSnapshotsById(String mpId, String targetStore) throws NotFoundException;
302
303 /**
304 * Moves a specific version of a given mediapackage ID to a new store
305 *
306 * @param mpId
307 * The mediapackage ID to move
308 * @param version
309 * The version to move
310 * @param targetStore
311 * The store ID to move this version of the mediapackage to
312 * @throws NotFoundException
313 */
314 void moveSnapshotsByIdAndVersion(String mpId, Version version, String targetStore) throws NotFoundException;
315
316 /**
317 * Moves all versions of all mediapackages archived within a data range to a new storage location.
318 *
319 * @param start
320 * The start {@link Date} to filter by
321 * @param end
322 * The end{@link Date} to filter by
323 * @param targetStore
324 * THe store ID to move the snapshots to
325 * @throws NotFoundException
326 */
327 void moveSnapshotsByDate(Date start, Date end, String targetStore) throws NotFoundException;
328
329 /**
330 * Moves all versions of a mediapackage archived within a data range to a new storage location.
331 *
332 * @param mpId
333 * The mediapackage ID to filter for
334 * @param start
335 * The start {@link Date} to filter by
336 * @param end
337 * The end{@link Date} to filter by
338 * @param targetStore
339 * THe store ID to move the snapshots to
340 * @throws NotFoundException
341 */
342 void moveSnapshotsByIdAndDate(String mpId, Date start, Date end, String targetStore) throws NotFoundException;
343
344 /* Properties */
345
346 /**
347 * Set a property. Use this method to either insert a new property or update an existing one.
348 * Properties are stored per episode.
349 *
350 * @return false, if the referenced episode does not exist.
351 */
352 boolean setProperty(Property property);
353
354 /**
355 * Select all properties for a specific media package.
356 *
357 * @param mediaPackageId
358 * Media package identifier to check for
359 * @param namespace
360 * Namespace to limit the search to
361 * @return List of properties
362 */
363 List<Property> selectProperties(String mediaPackageId, String namespace);
364
365 /**
366 * Delete all properties for a given media package identifier
367 *
368 * @param mediaPackageId
369 * Media package identifier
370 * @return Number of deleted properties
371 */
372 int deleteProperties(String mediaPackageId);
373
374 /**
375 * Delete all properties for a given media package identifier and namespace.
376 *
377 * @param mediaPackageId
378 * Media package identifier
379 * @param namespace
380 * A namespace prefix to use for deletion
381 * @return Number of deleted properties
382 */
383 int deleteProperties(String mediaPackageId, String namespace);
384
385 /**
386 * Delete all properties for a given media package identifier and namespace.
387 * Restricts access based on the current user
388 *
389 * @param mediaPackageId
390 * Media package identifier
391 * @param namespace
392 * A namespace prefix to use for deletion
393 * @return Number of deleted properties
394 */
395 int deletePropertiesWithCurrentUser(String mediaPackageId, String namespace);
396
397
398 /* Misc. */
399
400 /**
401 * Deserialize a version from a string. This is the inverse function of {@link Version#toString()}.
402 *
403 * @return a version or none, if no version can be archived from the given string
404 */
405 Optional<Version> toVersion(String version);
406
407 /**
408 * Count the number of events stored for a given organization.
409 *
410 * @param organization
411 * The organization to check.
412 * This may be `null` to not filter for an organization which is significantly faster.
413 * @return Number of events
414 */
415 long countEvents(String organization);
416
417 /**
418 * Count the number of snapshots stored for a given organization.
419 *
420 * @param organization
421 * The organization to check
422 * @return Number of snapshots
423 */
424 long countSnapshots(String organization);
425
426 /**
427 * Count the number of assets
428 *
429 * @return Number of assets
430 */
431 long countAssets();
432
433 /**
434 * Count the number of properties
435 *
436 * @return Number of properties
437 */
438 long countProperties();
439
440 /**
441 * Trigger search index update for event.
442 *
443 * @param mediaPackageId
444 * The event ID to trigger an index update for
445 */
446 void triggerIndexUpdate(String mediaPackageId) throws NotFoundException, UnauthorizedException;
447 }