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.query.AQueryBuilder;
24 import org.opencastproject.assetmanager.api.query.RichAResult;
25 import org.opencastproject.assetmanager.api.storage.AssetStore;
26 import org.opencastproject.mediapackage.MediaPackage;
27 import org.opencastproject.security.api.UnauthorizedException;
28 import org.opencastproject.util.NotFoundException;
29
30 import java.util.Date;
31 import java.util.List;
32 import java.util.Optional;
33
34 /**
35 * The AssetManager stores versioned {@linkplain Snapshot snapshots} of media packages.
36 * <p>
37 * It also supports the association of {@linkplain Property properties} to a
38 * history of snapshots which is called an episode.
39 *
40 * <h2>Terms</h2>
41 * <h3>Snapshot</h3>
42 * A snapshot saves a particular version of a media package. Snapshots are
43 * immutable and can only be deleted.
44 *
45 * <h3>Episode</h3>
46 * An episode is the set of snapshots of a media package.
47 *
48 * <h3>Properties</h3>
49 * Properties are associated with an episode and have a volatile character.
50 * They support the quick and easy storage of meta data.
51 * This removes the need for services to create their own persistence layer if
52 * they want to associate metadata with a media package.
53 *
54 * <h2>Notes</h2>
55 * Media package IDs are considered to be unique throughout the whole system.
56 * The organization ID is just a discriminator and not necessary to uniquely identify a media package.
57 */
58 public interface AssetManager {
59 String DEFAULT_OWNER = "default";
60
61 /**
62 * Get the media package from the lates snapshot.
63 *
64 * @param mediaPackageId
65 * @return mediapackage
66 */
67 Optional<MediaPackage> getMediaPackage(String mediaPackageId);
68
69 /**
70 * Get the asset that is uniquely identified by the triple {version, media package ID, media package element ID}.
71 *
72 * @param version the version
73 * @param mpId the media package ID
74 * @param mpeId the media package element ID
75 * @return the asset or none, if no such asset exists
76 */
77 Optional<Asset> getAsset(Version version, String mpId, String mpeId);
78
79 /**
80 * Get an asset store by id (local or remote).
81 *
82 * @param storeId the store id
83 * @return the asset store if it exists
84 */
85 Optional<AssetStore> getAssetStore(String storeId);
86
87 /**
88 * Get the remote asset stores as a list.
89 *
90 * @return a list of asset stores
91 */
92 List<AssetStore> getRemoteAssetStores();
93
94 /**
95 * Get the local asset store.
96 *
97 * @return the asset store
98 */
99 AssetStore getLocalAssetStore();
100
101
102 /* Snapshots */
103
104 /**
105 * Check if any snapshot with the given media package identifier exists.
106 *
107 * @param mediaPackageId
108 * The media package identifier to check for
109 * @return If a snapshot exists for the given media package
110 */
111 boolean snapshotExists(String mediaPackageId);
112
113 /**
114 * Check if any snapshot with the given media package identifier exists.
115 *
116 * @param mediaPackageId
117 * The media package identifier to check for
118 * @param organization
119 * The organization to limit the search to
120 * @return If a snapshot exists for the given media package
121 */
122 boolean snapshotExists(String mediaPackageId, String organization);
123
124 /**
125 * Returns a stream of {@link RichAResult} filtered by mediapackage IDs
126 *
127 * @param mpId
128 * The mediapackage ID to filter results for
129 * @return
130 * The {@link RichAResult} stream filtered by mediapackage ID
131 */
132 RichAResult getSnapshotsById(String mpId);
133
134 /**
135 * Returns a stream of {@link RichAResult} filtered by mediapackage IDs. This stream
136 * consists of all versions of all mediapackage ordered by the Version
137 *
138 * @param mpId
139 * The mediapackage ID to filter results for
140 * @param asc
141 * The asc {@link Boolean} decides if to order ascending (true) or descending (false)
142 * @return
143 * The {@link RichAResult} stream filtered by mediapackage ID
144 */
145 RichAResult getSnapshotsByIdOrderedByVersion(String mpId, boolean asc);
146
147 /**
148 * Returns a stream of {@link RichAResult} filtered by mediapackage ID and version
149 *
150 * @param mpId
151 * The mediapackage ID to filter results for
152 * @param version
153 * The version to filter results for
154 * @return
155 * The {@link RichAResult} stream filtered by mediapackage ID
156 */
157 RichAResult getSnapshotsByIdAndVersion(String mpId, Version version);
158
159 /**
160 * Returns a stream of {@link RichAResult} filtered by date. This stream
161 * consists of all versions of all mediapackages archived within the date range.
162 *
163 * @param start
164 * The start {@link Date} to filter by
165 * @param end
166 * The end{@link Date} to filter by
167 * @return
168 * The {@link RichAResult} stream filtered by date
169 */
170 RichAResult getSnapshotsByDate(Date start, Date end);
171
172 /**
173 * Returns a stream of {@link RichAResult} filtered by date. This stream consists of all
174 * a mediapackages which have at least one version archived within the date range.
175 *
176 * @param start
177 * The start {@link Date} to filter by
178 * @param end
179 * The end{@link Date} to filter by
180 * @return
181 * The {@link RichAResult} stream filtered by date
182 */
183 RichAResult getSnapshotsByDateOrderedById(Date start, Date end);
184
185 /**
186 * Returns a stream of {@link RichAResult} filtered by date and mediapackage. This stream consists of all versions of
187 * a mediapackage archived within the date range.
188 *
189 * @param mpId
190 * The mediapackage ID to filter for
191 * @param start
192 * The start {@link Date} to filter by
193 * @param end
194 * The end{@link Date} to filter by
195 * @return
196 * The {@link RichAResult} stream filtered by date
197 */
198 RichAResult getSnapshotsByIdAndDate(String mpId, Date start, Date end);
199
200 /**
201 * Returns a stream of {@link RichAResult} filtered by date and mediapackage.
202 * This stream consists of all versions of a mediapackage archived within the
203 * date range ordered by there Version.
204 *
205 * @param mpId
206 * The mediapackage ID to filter for
207 * @param start
208 * The start {@link Date} to filter by
209 * @param end
210 * The end {@link Date} to filter by
211 * @param asc
212 * The asc {@link Boolean} decides if to order ascending (true) or descending (false)
213 * @return
214 * The {@link RichAResult} stream filtered by date
215 */
216 RichAResult getSnapshotsByIdAndDateOrderedByVersion(String mpId, Date start, Date end, boolean asc);
217
218 /**
219 * Take a versioned snapshot of a media package.
220 * <p>
221 * Snapshot are tagged with string identifying the owner. Only the owner
222 * of a snapshot is allowed to delete it.
223 * Ownership only affects the deletion of a snapshot.
224 *
225 * @param owner
226 * the owner of the snapshot, e.g. the name of the calling service
227 */
228 Snapshot takeSnapshot(String owner, MediaPackage mp);
229
230 /**
231 * Take a versioned snapshot of a media package using the owner of the last
232 * snapshot or the default owner if it does not exist.
233 *
234 * @param mediaPackage
235 * The media package to snapshot
236 * @return A new snapshot
237 */
238 Snapshot takeSnapshot(MediaPackage mediaPackage);
239
240 /**
241 * Move snapshot from current store to new store
242 * Note: This may require downloading and re-uploading
243 *
244 * @param version The version to move
245 * @param mpId The media package to move
246 * @param storeId The store to move to
247 * @throws NotFoundException
248 */
249 void moveSnapshotToStore(Version version, String mpId, String storeId) throws NotFoundException;
250
251 /**
252 * Moves all versions of a given mediapackage ID from their respective source stores to a single target store
253 * @param mpId
254 * The mediapackage ID to move
255 * @param targetStore
256 * The store ID to move all versions of this mediapackage to
257 * @throws NotFoundException
258 */
259 void moveSnapshotsById(String mpId, String targetStore) throws NotFoundException;
260
261 /**
262 * Moves a specific version of a given mediapackage ID to a new store
263 *
264 * @param mpId
265 * The mediapackage ID to move
266 * @param version
267 * The version to move
268 * @param targetStore
269 * The store ID to move this version of the mediapackage to
270 * @throws NotFoundException
271 */
272 void moveSnapshotsByIdAndVersion(String mpId, Version version, String targetStore) throws NotFoundException;
273
274 /**
275 * Moves all versions of all mediapackages archived within a data range to a new storage location.
276 *
277 * @param start
278 * The start {@link Date} to filter by
279 * @param end
280 * The end{@link Date} to filter by
281 * @param targetStore
282 * THe store ID to move the snapshots to
283 * @throws NotFoundException
284 */
285 void moveSnapshotsByDate(Date start, Date end, String targetStore) throws NotFoundException;
286
287 /**
288 * Moves all versions of a mediapackage archived within a data range to a new storage location.
289 *
290 * @param mpId
291 * The mediapackage ID to filter for
292 * @param start
293 * The start {@link Date} to filter by
294 * @param end
295 * The end{@link Date} to filter by
296 * @param targetStore
297 * THe store ID to move the snapshots to
298 * @throws NotFoundException
299 */
300 void moveSnapshotsByIdAndDate(String mpId, Date start, Date end, String targetStore) throws NotFoundException;
301
302 /* Properties */
303
304 /**
305 * Set a property. Use this method to either insert a new property or update an existing one.
306 * Properties are stored per episode.
307 *
308 * @return false, if the referenced episode does not exist.
309 */
310 boolean setProperty(Property property);
311
312 /**
313 * Select all properties for a specific media package.
314 *
315 * @param mediaPackageId
316 * Media package identifier to check for
317 * @param namespace
318 * Namespace to limit the search to
319 * @return List of properties
320 */
321 List<Property> selectProperties(String mediaPackageId, String namespace);
322
323 /**
324 * Delete all properties for a given media package identifier
325 *
326 * @param mediaPackageId
327 * Media package identifier
328 * @return Number of deleted properties
329 */
330 int deleteProperties(String mediaPackageId);
331
332 /**
333 * Delete all properties for a given media package identifier and namespace.
334 *
335 * @param mediaPackageId
336 * Media package identifier
337 * @param namespace
338 * A namespace prefix to use for deletion
339 * @return Number of deleted properties
340 */
341 int deleteProperties(String mediaPackageId, String namespace);
342
343
344 /* Misc. */
345
346 /** Create a new query builder. */
347 AQueryBuilder createQuery();
348
349 /**
350 * Deserialize a version from a string. This is the inverse function of {@link Version#toString()}.
351 *
352 * @return a version or none, if no version can be archived from the given string
353 */
354 Optional<Version> toVersion(String version);
355
356 /**
357 * Count the number of events stored for a given organization.
358 *
359 * @param organization
360 * The organization to check.
361 * This may be `null` to not filter for an organization which is significantly faster.
362 * @return Number of events
363 */
364 long countEvents(String organization);
365
366 /**
367 * Trigger search index update for event.
368 *
369 * @param mediaPackageId
370 * The event ID to trigger an index update for
371 */
372 void triggerIndexUpdate(String mediaPackageId) throws NotFoundException, UnauthorizedException;
373 }