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 package org.opencastproject.inspection.api;
23
24 import org.opencastproject.job.api.Job;
25 import org.opencastproject.mediapackage.MediaPackageElement;
26 import org.opencastproject.mediapackage.MediaPackageException;
27
28 import java.net.URI;
29 import java.util.Map;
30
31 /**
32 * Anayzes media to determine its technical metadata.
33 */
34 public interface MediaInspectionService {
35
36 /**
37 * The namespace distinguishing media inspection jobs from other types
38 */
39 String JOB_TYPE = "org.opencastproject.inspection";
40
41 /**
42 * Inspect a track based on a given uri to the track and put the gathered data into the track
43 *
44 * @param uri
45 * the uri to a track in a media package
46 * @return the receipt of this job, that can be used to check the current status of inspect method and retrieve track
47 * with added metadata when done
48 * @throws MediaInspectionException
49 * if there is a failure during media package update
50 */
51 Job inspect(URI uri) throws MediaInspectionException;
52
53 /**
54 * Inspect a track based on a given uri to the track and put the gathered data into the track
55 *
56 * @param uri
57 * the uri to a track in a media package
58 * @param options
59 * Options in form of key/value pairs that are passed to the Media Inspection Service implementation.
60 * Those options may be implementation specific. The implementation is supposed to raise an
61 * exception in case unsupported options are encountered.
62 * Value may not be null.
63 * @return the receipt of this job, that can be used to check the current status of inspect method and retrieve track
64 * with added metadata when done
65 * @throws MediaInspectionException
66 * if there is a failure during media package update
67 */
68 Job inspect(URI uri, Map<String, String> options) throws MediaInspectionException;
69
70 /**
71 * Equip an existing media package element with automatically generated metadata
72 *
73 * @param original
74 * The original media package element that will be inspected
75 * @param override
76 * In case of conflict between existing and automatically obtained metadata this switch selects preference.
77 * False..The original metadata will be kept, True..The new metadata will be used.
78 * @return the receipt of this job, that can be used to check the current status of enrich method and retrieve
79 * enriched element when done
80 * @throws MediaInspectionException
81 * if there is a failure during media package update
82 * @throws MediaPackageException
83 * if the element is invalid
84 */
85 Job enrich(MediaPackageElement original, boolean override) throws MediaInspectionException,
86 MediaPackageException;
87
88 /**
89 * Equip an existing media package element with automatically generated metadata
90 *
91 * @param original
92 * The original media package element that will be inspected
93 * @param override
94 * In case of conflict between existing and automatically obtained metadata this switch selects preference.
95 * False..The original metadata will be kept, True..The new metadata will be used.
96 * @param options
97 * Options in form of key/value pairs that are passed to the MediaInspectionService implementation.
98 * Those options may be implementation specific. The implementation is supposed to raise an
99 * exception in case unsupported options are encountered.
100 * Value may not be null.
101 * @return the receipt of this job, that can be used to check the current status of enrich method and retrieve
102 * enriched element when done
103 * @throws MediaInspectionException
104 * if there is a failure during media package update
105 * @throws MediaPackageException
106 * if the element is invalid
107 */
108 Job enrich(MediaPackageElement original, boolean override, Map<String, String> options)
109 throws MediaInspectionException, MediaPackageException;
110 }