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.usertracking.api;
23
24 import org.opencastproject.util.NotFoundException;
25
26 import java.text.ParseException;
27
28
29
30 /**
31 * Provides annotation capabilities, possibly to the engage tools, possibly to other services.
32 */
33 public interface UserTrackingService {
34
35 /**
36 * Adds a new annotation to the database and returns the event with an updated annotationId, to make sure the
37 * annotationId stays unique
38 *
39 * @param a
40 * The UserAction that will be added to the database
41 * @param session
42 * The UserSession associated with this footprint
43 * @return the updated annotation, with a new ID. NULL if there are errors while adding the annotation.
44 * @throws UserTrackingException
45 * if the user tracking service encounters an error
46 */
47 UserAction addUserFootprint(UserAction a, UserSession session) throws UserTrackingException;
48
49 /**
50 * Adds a new tracking event to the database and returns the event with an updated annotationId, to make sure the
51 * annotationId stays unique
52 *
53 * @param a
54 * The UserAction that will be added to the database
55 * @param session
56 * The UserSession associated with this footprint
57 * @return the updated annotation, with a new ID. NULL if there are errors while adding the annotation.
58 * @throws UserTrackingException
59 * if the user tracking service encounters an error
60 */
61 UserAction addUserTrackingEvent(UserAction a, UserSession session) throws UserTrackingException;
62
63 /**
64 * Returns annotations
65 *
66 * @param offset
67 * the offset
68 * @param limit
69 * the limit
70 * @return the annotation list
71 * @throws UserTrackingException
72 * if the user tracking service encounters an error
73 */
74 UserActionList getUserActions(int offset, int limit) throws UserTrackingException;
75
76 /**
77 * Returns annotations of a given key
78 *
79 * @param key
80 * The annotation key
81 * @param offset
82 * the offset
83 * @param limit
84 * the limit
85 * @return the annotation list
86 * @throws UserTrackingException
87 * if the user tracking service encounters an error
88 */
89 UserActionList getUserActionsByType(String key, int offset, int limit) throws UserTrackingException;
90
91 /**
92 * Returns annotations of a given day (YYYYMMDD)
93 *
94 * @param day
95 * The day in the format of YYYYMMDD
96 * @param offset
97 * the offset
98 * @param limit
99 * the limit
100 * @return the annotation list
101 * @throws UserTrackingException
102 * if the user tracking service encounters an error
103 */
104 UserActionList getUserActionsByDay(String day, int offset, int limit) throws UserTrackingException;
105
106 /**
107 * Returns annotations of a given key and day
108 *
109 * @param key
110 * the annotation key
111 * @param day
112 * the day
113 * @param offset
114 * the offset
115 * @param limit
116 * the limit
117 * @return the annotation list
118 * @throws UserTrackingException
119 * if the user tracking service encounters an error
120 */
121 UserActionList getUserActionsByTypeAndDay(String key, String day, int offset, int limit) throws UserTrackingException;
122
123 /**
124 * Returns annotations of a given key and mediapackage id
125 *
126 * @param key
127 * the annotation key
128 * @param mediapackageId
129 * the mediapackage id
130 * @param offset
131 * the offset
132 * @param limit
133 * the limit
134 * @return the annotation list
135 * @throws UserTrackingException
136 * if the user tracking service encounters an error
137 */
138 UserActionList getUserActionsByTypeAndMediapackageId(String key, String mediapackageId, int offset, int limit)
139 throws UserTrackingException;
140
141 /**
142 * Returns annotations of a given key and mediapackage id ordered by date.
143 *
144 * @param key
145 * the annotation key
146 * @param mediapackageId
147 * the mediapackage id
148 * @param offset
149 * the offset
150 * @param limit
151 * the limit
152 * @return the annotation list
153 * @throws UserTrackingException
154 * if the user tracking service encounters an error
155 */
156 UserActionList getUserActionsByTypeAndMediapackageIdByDate(String key, String mediapackageId, int offset, int limit)
157 throws UserTrackingException;
158
159
160 /**
161 * Returns annotations of a given key and mediapackage id ordered descending by date.
162 *
163 * @param key
164 * the annotation key
165 * @param mediapackageId
166 * the mediapackage id
167 * @param offset
168 * the offset
169 * @param limit
170 * the limit
171 * @return the annotation list
172 * @throws UserTrackingException
173 * if the user tracking service encounters an error
174 */
175 UserActionList getUserActionsByTypeAndMediapackageIdByDescendingDate(String key, String mediapackageId, int offset,
176 int limit) throws UserTrackingException;
177
178 /**
179 * Returns the views of a mediapackage
180 *
181 * @param mediapackageId
182 * the mediapackeId
183 * @return the views
184 * @throws UserTrackingException
185 * if the user tracking service encounters an error
186 */
187 int getViews(String mediapackageId) throws UserTrackingException;
188
189 /**
190 * Returns a report
191 *
192 * @param from
193 * The from day key
194 * @param to
195 * The to day key
196 * @param offset
197 * the offset
198 * @param limit
199 * the limit
200 * @return the report
201 * @throws UserTrackingException
202 * if the user tracking service encounters an error
203 */
204 Report getReport(String from, String to, int offset, int limit) throws UserTrackingException, ParseException;
205
206 /**
207 * Returns a report
208 *
209 * @param offset
210 * the offset
211 * @param limit
212 * the limit
213 * @return the report
214 * @throws UserTrackingException
215 * if the user tracking service encounters an error
216 */
217 Report getReport(int offset, int limit) throws UserTrackingException;
218
219 /**
220 * Returns a list of footprints, if a userId is passed only the footprints of that user are returned.
221 *
222 * @param mediapackageId
223 * The mediapackageId
224 * @param userId
225 * The userId is optional
226 * @return the footprintList
227 * @throws UserTrackingException
228 * if the user tracking service encounters an error
229 */
230 FootprintList getFootprints(String mediapackageId, String userId) throws UserTrackingException;
231
232 /**
233 * Get a single user action by its identifier.
234 *
235 * @param id
236 * the user action identifier
237 * @return the user action
238 * @throws UserTrackingException
239 * if the user tracking service encounters an error
240 * @throws NotFoundException
241 * if the no user action with this identifier exists
242 */
243 UserAction getUserAction(Long id) throws UserTrackingException, NotFoundException;
244
245 /**
246 * Returns the flag turning user tracking on or off.
247 * Turning user tracking off disables the detailed information gathering, but does *not* disable footprint gathering.
248 *
249 * @return True if detailed user tracking should be gathered, false otherwise
250 */
251 boolean getUserTrackingEnabled();
252
253 }