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.annotation.api;
23
24 import org.opencastproject.util.NotFoundException;
25
26 /**
27 * Manages user annotations within media.
28 */
29 public interface AnnotationService {
30 /**
31 * Adds a new annotation to the database and returns the event with an updated annotationId, to make sure the
32 * annotationId stays unique
33 *
34 * @param a
35 * The Annotation that will be added to the database
36 * @return the updated annotation, with a new ID. NULL if there are errors while adding the annotation.
37 */
38 Annotation addAnnotation(Annotation a);
39
40 /**
41 * Changes an annotation in the database it uses the annotationId to overwrite the value. It
42 * returns the event with an updated annotation.
43 *
44 * @param a
45 * The Annotation that will be changed in the database
46 * @return the updated annotation. NULL if there are errors while changing the annotation.
47 */
48 Annotation changeAnnotation(Annotation a) throws NotFoundException;
49
50 /**
51 * Remove a given annotation from database
52 *
53 * @param a
54 * The Annotation that will be removed from the database
55 * @return true if successfull removed, false else.
56 */
57 boolean removeAnnotation(Annotation a);
58
59 /**
60 * Gets an annotation by its identifier.
61 *
62 * @param id
63 * the annotation identifier
64 * @return the annotation
65 * @throws NotFoundException if there is no annotation with this identifier
66 */
67 Annotation getAnnotation(long id) throws NotFoundException;
68
69 /**
70 * Returns annotations
71 *
72 * @param offset
73 * the offset
74 * @param limit
75 * the limit
76 * @return the annotation list
77 */
78 AnnotationList getAnnotations(int offset, int limit);
79
80
81 /**
82 * Returns annotations of a given mediapackage ID
83 *
84 * @param mediapackageId
85 * The mediapackage ID
86 * @param offset
87 * the offset
88 * @param limit
89 * the limit
90 * @return the annotation list
91 */
92 AnnotationList getAnnotationsByMediapackageId(String mediapackageId, int offset, int limit);
93
94 /**
95 * Returns annotations of a given type
96 *
97 * @param type
98 * The annotation type
99 * @param offset
100 * the offset
101 * @param limit
102 * the limit
103 * @return the annotation list
104 */
105 AnnotationList getAnnotationsByType(String type, int offset, int limit);
106
107 /**
108 * Returns annotations of a given day (YYYYMMDD)
109 *
110 * @param day
111 * The day in the format of YYYYMMDD
112 * @param offset
113 * the offset
114 * @param limit
115 * the limit
116 * @return the annotation list
117 */
118 AnnotationList getAnnotationsByDay(String day, int offset, int limit);
119
120 /**
121 * Returns annotations of a given type and day
122 *
123 * @param type
124 * the annotation type
125 * @param day
126 * the day
127 * @param offset
128 * the offset
129 * @param limit
130 * the limit
131 * @return the annotation list
132 */
133 AnnotationList getAnnotationsByTypeAndDay(String type, String day, int offset, int limit);
134
135 /**
136 * Returns annotations of a given type and mediapackage id
137 *
138 * @param type
139 * the annotation type
140 * @param mediapackageId
141 * the mediapackage id
142 * @param offset
143 * the offset
144 * @param limit
145 * the limit
146 * @return the annotation list
147 */
148 AnnotationList getAnnotationsByTypeAndMediapackageId(String type, String mediapackageId, int offset, int limit);
149
150 }