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
22
23 package org.opencastproject.mediapackage;
24
25 import org.opencastproject.mediapackage.identifier.Id;
26
27 import java.net.URI;
28 import java.util.Collection;
29 import java.util.Date;
30
31 import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
32
33 /**
34 * Interface for a media package, which is a data container moving through the system, containing metadata, tracks and
35 * attachments.
36 */
37 @XmlJavaTypeAdapter(MediaPackageImpl.Adapter.class)
38 public interface MediaPackage extends Cloneable {
39
40 /**
41 * Returns the media package identifier.
42 *
43 * @return the identifier
44 */
45 Id getIdentifier();
46
47 void setIdentifier(Id id);
48
49 void setTitle(String title);
50
51 /**
52 * Returns the title for the associated series, if any.
53 *
54 * @return The series title
55 *
56 * @deprecated This is not guaranteed to be correct. Use the metadata contained in the Dublin Core catalog instead.
57 */
58 @Deprecated
59 String getSeriesTitle();
60
61 void setSeriesTitle(String seriesTitle);
62
63 /**
64 * Returns the title of the episode that this mediapackage represents.
65 *
66 * @return The episode title
67 *
68 * @deprecated This is not guaranteed to be correct. Use the metadata contained in the Dublin Core catalog instead.
69 */
70 @Deprecated
71 String getTitle();
72
73 void addCreator(String creator);
74
75 void removeCreator(String creator);
76
77 /**
78 * Returns the names of the institutions or people who created this mediapackage
79 *
80 * @return the creators of this mediapackage
81 *
82 * @deprecated This is not guaranteed to be correct. Use the metadata contained in the Dublin Core catalog instead.
83 */
84 @Deprecated
85 String[] getCreators();
86
87 void setSeries(String identifier);
88
89 /**
90 * Returns the series, if any, to which this mediapackage belongs
91 *
92 * @return the series
93 */
94 String getSeries();
95
96 void setLicense(String license);
97
98 /**
99 * The license for the content in this mediapackage
100 *
101 * @return the license
102 *
103 * @deprecated This is not guaranteed to be correct. Use the metadata contained in the Dublin Core catalog instead.
104 */
105 @Deprecated
106 String getLicense();
107
108 void addContributor(String contributor);
109
110 void removeContributor(String contributor);
111
112 /**
113 * Returns the names of the institutions or people who contributed to the content within this mediapackage
114 *
115 * @return the contributors
116 *
117 * @deprecated This is not guaranteed to be correct. Use the metadata contained in the Dublin Core catalog instead.
118 */
119 @Deprecated
120 String[] getContributors();
121
122 void setLanguage(String language);
123
124 /**
125 * Returns the language written and/or spoken in the media content of this mediapackage
126 *
127 * @return the language
128 *
129 * @deprecated This is not guaranteed to be correct. Use the metadata contained in the Dublin Core catalog instead.
130 */
131 @Deprecated
132 String getLanguage();
133
134 void addSubject(String subject);
135
136 void removeSubject(String subject);
137
138 /**
139 * The keywords describing the subject(s) or categories describing the content of this mediapackage
140 *
141 * @return the subjects
142 *
143 * @deprecated This is not guaranteed to be correct. Use the metadata contained in the Dublin Core catalog instead.
144 */
145 @Deprecated
146 String[] getSubjects();
147
148 void setDate(Date date);
149
150 /**
151 * Returns the media package start time.
152 *
153 * @return the start time
154 *
155 * @deprecated This is not guaranteed to be correct. Use the metadata contained in the Dublin Core catalog instead.
156 */
157 @Deprecated
158 Date getDate();
159
160 /**
161 * Returns the media package duration in milliseconds or <code>null</code> if no duration is available.
162 *
163 * @return the duration
164 *
165 * @deprecated This is not guaranteed to be correct. Use the metadata contained in the Dublin Core catalog instead.
166 */
167 @Deprecated
168 Long getDuration();
169
170 /**
171 * Sets the duration of the media package in milliseconds. This method will throw an {@link IllegalStateException} if
172 * tracks have been added to the mediapackage already. Also note that as soon as the first track is added, the
173 * duration will be udpated according to the track's length.
174 *
175 * @param duration
176 * the duration in milliseconds
177 * @throws IllegalStateException
178 * if the mediapackage already contains a track
179 */
180 void setDuration(Long duration) throws IllegalStateException;
181
182 /**
183 * Returns <code>true</code> if the given element is part of the media package.
184 *
185 * @param element
186 * the element
187 * @return <code>true</code> if the element belongs to the media package
188 */
189 boolean contains(MediaPackageElement element);
190
191 /**
192 * Returns an iteration of the media package elements.
193 *
194 * @return the media package elements
195 */
196 Iterable<MediaPackageElement> elements();
197
198 /**
199 * Returns all the elements.
200 *
201 * @return the elements
202 */
203 MediaPackageElement[] getElements();
204
205 /**
206 * Returns the element that is identified by the given reference or <code>null</code> if no such element exists.
207 *
208 * @param reference
209 * the reference
210 * @return the element
211 */
212 MediaPackageElement getElementByReference(MediaPackageReference reference);
213
214 /**
215 * Returns the element that is identified by the given identifier or <code>null</code> if no such element exists.
216 *
217 * @param id
218 * the element identifier
219 * @return the element
220 */
221 MediaPackageElement getElementById(String id);
222
223 /**
224 * Returns the elements that are tagged with any of the given tags or an empty array if no such elements are found. If
225 * any of the tags in the <code>tags</code> collection start with a '-' character, any elements matching the tag will
226 * be excluded from the returned MediaPackageElement[]. If <code>tags</code> is empty or null, all elements are
227 * returned.
228 *
229 * @param tags
230 * the tags
231 * @return the elements
232 */
233 MediaPackageElement[] getElementsByTags(Collection<String> tags);
234
235 /**
236 * Returns all elements of this media package with the given flavor.
237 *
238 * @return the media package elements
239 */
240 MediaPackageElement[] getElementsByFlavor(MediaPackageElementFlavor flavor);
241
242 /**
243 * Returns the track identified by <code>trackId</code> or <code>null</code> if that track doesn't exists.
244 *
245 * @param trackId
246 * the track identifier
247 * @return the tracks
248 */
249 Track getTrack(String trackId);
250
251 /**
252 * Returns the tracks that are part of this media package.
253 *
254 * @return the tracks
255 */
256 Track[] getTracks();
257
258 /**
259 * Returns the tracks that are tagged with the given tag or an empty array if no such tracks are found.
260 *
261 * @param tag
262 * the tag
263 * @return the tracks
264 */
265 Track[] getTracksByTag(String tag);
266
267 /**
268 * Returns the tracks that are tagged with any of the given tags or an empty array if no such elements are found. If
269 * any of the tags in the <code>tags</code> collection start with a '-' character, any elements matching the tag will
270 * be excluded from the returned Track[]. If <code>tags</code> is empty or null, all tracks are returned.
271 *
272 * @param tags
273 * the tags
274 * @return the tracks
275 */
276 Track[] getTracksByTags(Collection<String> tags);
277
278 /**
279 * Returns the tracks that are part of this media package and match the given flavor as defined in {@link Track}.
280 *
281 * @param flavor
282 * the track's flavor
283 * @return the tracks with the specified flavor
284 */
285 Track[] getTracks(MediaPackageElementFlavor flavor);
286
287 /**
288 * Returns <code>true</code> if the media package contains media tracks of any kind.
289 *
290 * @return <code>true</code> if the media package contains tracks
291 */
292 boolean hasTracks();
293
294 /**
295 * Returns the attachment identified by <code>attachmentId</code> or <code>null</code> if that attachment does not
296 * exist.
297 *
298 * @param attachmentId
299 * the attachment identifier
300 * @return the attachments
301 */
302 Attachment getAttachment(String attachmentId);
303
304 /**
305 * Returns the attachments that are part of this media package.
306 *
307 * @return the attachments
308 */
309 Attachment[] getAttachments();
310
311 /**
312 * Returns the attachments that are part of this media package and match the specified flavor.
313 *
314 * @param flavor
315 * the attachment flavor
316 * @return the attachments
317 */
318 Attachment[] getAttachments(MediaPackageElementFlavor flavor);
319
320 /**
321 * Returns the presentations that are part of this media package.
322 *
323 * @return the attachments
324 */
325 Publication[] getPublications();
326
327 /**
328 * Returns the catalog identified by <code>catalogId</code> or <code>null</code> if that catalog doesn't exists.
329 *
330 * @param catalogId
331 * the catalog identifier
332 * @return the catalogs
333 */
334 Catalog getCatalog(String catalogId);
335
336 /**
337 * Returns the catalogs associated with this media package.
338 *
339 * @return the catalogs
340 */
341 Catalog[] getCatalogs();
342
343 /**
344 * Returns the catalogs that are tagged with any of the given tags or an empty array if no such elements are found. If
345 * any of the tags in the <code>tags</code> collection start with a '-' character, any elements matching the tag will
346 * be excluded from the returned Catalog[]. If <code>tags</code> is empty or null, all catalogs are returned.
347 *
348 * @param tags
349 * the tags
350 * @return the catalogs
351 */
352 Catalog[] getCatalogsByTags(Collection<String> tags);
353
354 /**
355 * Returns the catalogs associated with this media package that matches the specified flavor.
356 *
357 * @param flavor
358 * the catalog type
359 * @return the media package catalogs
360 */
361 Catalog[] getCatalogs(MediaPackageElementFlavor flavor);
362
363 /**
364 * Returns the catalogs that are part of this media package and are refering to the element identified by
365 * <code>reference</code>.
366 *
367 * @param reference
368 * the reference
369 * @return the catalogs with the specified reference
370 */
371 Catalog[] getCatalogs(MediaPackageReference reference);
372
373 /**
374 * Returns the catalogs that are part of this media package and are refering to the element identified by
375 * <code>reference</code>.
376 *
377 * @param flavor
378 * the element flavor
379 * @param reference
380 * the reference
381 * @return the catalogs with the specified reference
382 */
383 Catalog[] getCatalogs(MediaPackageElementFlavor flavor, MediaPackageReference reference);
384
385 /**
386 * Returns media package elements that are neither, attachments, catalogs nor tracks.
387 *
388 * @return the other media package elements
389 */
390 MediaPackageElement[] getUnclassifiedElements();
391
392 /**
393 * Adds an arbitrary {@link URI} to this media package, utilizing a {@link MediaPackageBuilder} to create a suitable
394 * media package element out of the url. If the content cannot be recognized as being either a metadata catalog or
395 * multimedia track, it is added as an attachment.
396 *
397 * @param uri
398 * the element location
399 */
400 MediaPackageElement add(URI uri);
401
402 /**
403 * Adds an arbitrary {@link URI} to this media package, utilizing a {@link MediaPackageBuilder} to create a suitable
404 * media package element out of the url. If the content cannot be recognized as being either a metadata catalog or
405 * multimedia track, it is added as an attachment.
406 *
407 * @param uri
408 * the element location
409 * @param type
410 * the element type
411 * @param flavor
412 * the element flavor
413 */
414 MediaPackageElement add(URI uri, MediaPackageElement.Type type, MediaPackageElementFlavor flavor);
415
416 /**
417 * Adds an arbitrary {@link MediaPackageElement} to this media package.
418 *
419 * @param element
420 * the element
421 */
422 void add(MediaPackageElement element);
423
424 /**
425 * Adds a track to this media package, actually <em>moving</em> the underlying file in the filesystem. Use this method
426 * <em>only</em> if you do not need the track in its originial place anymore.
427 * <p>
428 * Depending on the implementation, this method may provide significant performance benefits over copying the track.
429 *
430 * @param track
431 * the track
432 */
433 void add(Track track);
434
435 /**
436 * Removes the element with the given identifier from the mediapackage and returns it.
437 *
438 * @param id
439 * the element identifier
440 */
441 MediaPackageElement removeElementById(String id);
442
443 /**
444 * Removes the track from the media package.
445 *
446 * @param track
447 * the track
448 */
449 void remove(Track track);
450
451 /**
452 * Adds catalog information to this media package.
453 *
454 * @param catalog
455 * the catalog
456 */
457 void add(Catalog catalog);
458
459 /**
460 * Removes the catalog from the media package.
461 *
462 * @param catalog
463 * the catalog
464 */
465 void remove(Catalog catalog);
466
467 /**
468 * Adds an attachment to this media package.
469 *
470 * @param attachment
471 * the attachment
472 */
473 void add(Attachment attachment);
474
475 /**
476 * Removes an arbitrary media package element.
477 *
478 * @param element
479 * the media package element
480 */
481 void remove(MediaPackageElement element);
482
483 /**
484 * Removes the attachment from the media package.
485 *
486 * @param attachment
487 * the attachment
488 */
489 void remove(Attachment attachment);
490
491 /**
492 * Adds an element to this media package that represents a derived version of <code>sourceElement</code>. Examples of
493 * a derived element could be an encoded version of a track or a converted version of a time text captions file.
494 * <p>
495 * This method will add <code>derviedElement</code> to the media package and add a reference to the original element
496 * <code>sourceElement</code>. Make sure that <code>derivedElement</code> features the right flavor, so that you are
497 * later able to look up derived work using {@link #getDerived(MediaPackageElement, MediaPackageElementFlavor)}.
498 *
499 * @param derivedElement
500 * the derived element
501 * @param sourceElement
502 * the source element
503 */
504 void addDerived(MediaPackageElement derivedElement, MediaPackageElement sourceElement);
505
506 /**
507 * Returns those media package elements that are derivates of <code>sourceElement</code> and feature the flavor
508 * <code>derivateFlavor</code>. Using this method, you could easily look up e. g. flash-encoded versions of the
509 * presenter track or converted versions of a time text captions file.
510 *
511 * @param sourceElement
512 * the original track, catalog or attachment
513 * @param derivateFlavor
514 * the derivate flavor you are looking for
515 * @return the derivates
516 */
517 MediaPackageElement[] getDerived(MediaPackageElement sourceElement, MediaPackageElementFlavor derivateFlavor);
518
519 /**
520 * Verifies the media package consistency by checking the media package elements for mimetypes and checksums.
521 *
522 * @throws MediaPackageException
523 * if an error occurs while checking the media package
524 */
525 void verify() throws MediaPackageException;
526
527 /**
528 * Creates a deep copy of the media package.
529 *
530 * @return the cloned media package
531 */
532 Object clone();
533
534 /**
535 * Whether the media package contains live tracks.
536 *
537 * @return if mp is live
538 */
539 boolean isLive();
540
541 }