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.scheduler.impl;
23
24 import org.opencastproject.scheduler.impl.persistence.ExtendedEventDto;
25 import org.opencastproject.util.NotFoundException;
26
27 import com.entwinemedia.fn.data.Opt;
28
29 import java.util.Date;
30 import java.util.List;
31 import java.util.Map;
32
33 /**
34 * Permanent storage for events. Does not support searching.
35 */
36 public interface SchedulerServiceDatabase {
37
38 /**
39 * Touches the most recent entry by updating its last modification date.
40 *
41 * @param agentId
42 * the capture agent identifier
43 * @throws SchedulerServiceDatabaseException
44 * if updating of the last modified value fails
45 */
46 void touchLastEntry(String agentId) throws SchedulerServiceDatabaseException;
47
48 /**
49 * Get the last modification date by an agent identifier
50 *
51 * @param agentId
52 * the capture agent identifier
53 * @return the last modification date
54 * @throws NotFoundException
55 * if the agent could not be found
56 * @throws SchedulerServiceDatabaseException
57 * if exception occurred
58 */
59 Date getLastModified(String agentId) throws NotFoundException, SchedulerServiceDatabaseException;
60
61 /**
62 * Get a {@link Map} of last modification dates of all existing capture agents.
63 *
64 * @return the last modified map
65 * @throws SchedulerServiceDatabaseException
66 * if exception occurred
67 */
68 Map<String, Date> getLastModifiedDates() throws SchedulerServiceDatabaseException;
69
70
71 /**
72 * Create or update an event identified by mediapackageId and organizationId
73 *
74 * @param mediapackageId
75 * the mediapackage ID
76 * @param organizationId
77 * the organization ID of the organization owning the event
78 * @param captureAgentId
79 * the capture agent ID of the capture agent this event is scheduled on
80 * @param start
81 * the recording start time
82 * @param end
83 * the recording end time
84 * @param source
85 * the source
86 * @param recordingState
87 * the recording state
88 * @param recordingLastHeard
89 * the recording last heard
90 * @param presenters
91 * the presenters
92 * @param lastModifiedDate
93 * the last modified date
94 * @param checksum
95 * the checksum
96 * @param workflowProperties
97 * the workflow properties
98 * @param captureAgentProperties
99 * the capture agent properties
100 * @throws SchedulerServiceDatabaseException in case the event cannot be stored.
101 */
102 void storeEvent(
103 String mediapackageId,
104 String organizationId,
105 Opt<String> captureAgentId,
106 Opt<Date> start,
107 Opt<Date> end,
108 Opt<String> source,
109 Opt<String> recordingState,
110 Opt<Long> recordingLastHeard,
111 Opt<String> presenters,
112 Opt<Date> lastModifiedDate,
113 Opt<String> checksum,
114 Opt<Map<String,String>> workflowProperties,
115 Opt<Map<String,String>> captureAgentProperties
116 ) throws SchedulerServiceDatabaseException;
117
118 /**
119 * Get the mediapackage IDs of all events scheduled on the given capture agent between the given start/end time.
120 * Events which are only partially contained within the given interval are also included in the result set. The
121 * results are ordered by start date ascending.
122 *
123 * @param captureAgentId
124 * the capture agent ID of the capture agent to check
125 * @param start
126 * the start date of the interval to check
127 * @param end
128 * the end date of the interval to check
129 * @param separationMillis
130 * number of milliseconds to prepend and append to given interval
131 * @return The mediapackage IDs of the events between start (inclusive) and end (inclusive) scheduled on the given
132 * capture agent.
133 * @throws SchedulerServiceDatabaseException
134 * If the database cannot be queried.
135 */
136 List<String> getEvents(String captureAgentId, Date start, Date end, int separationMillis) throws SchedulerServiceDatabaseException;
137
138 /**
139 * Retrieve all events matching given filter ordered by start time ascending.
140 *
141 * @param captureAgentId
142 * the capture agent id filter
143 * @param startsFrom
144 * the start from date filter
145 * @param startsTo
146 * the start to date filter
147 * @param endFrom
148 * the end from date filter
149 * @param endTo
150 * the end to date filter
151 * @param limit
152 * the maximum number of results to retrieve
153 * @return The events matching the given filter
154 * @throws SchedulerServiceDatabaseException
155 * If the database cannot be queried.
156 */
157 List<ExtendedEventDto> search(Opt<String> captureAgentId, Opt<Date> startsFrom, Opt<Date> startsTo, Opt<Date> endFrom, Opt<Date> endTo, Opt<Integer> limit) throws SchedulerServiceDatabaseException;
158
159 /**
160 * Retrieve all events which have a recording state and a recording last heard.
161 *
162 * @return all events which have a recording state and a recording last heard
163 * @throws SchedulerServiceDatabaseException
164 * If the database cannot be queried.
165 */
166 List<ExtendedEventDto> getKnownRecordings() throws SchedulerServiceDatabaseException;
167
168 /**
169 * Removes the extended event from persistent storage.
170 *
171 * @param mediapackageId
172 * ID of event to be removed
173 * @throws NotFoundException
174 * if there is no element with specified ID
175 * @throws SchedulerServiceDatabaseException
176 * if exception occurred
177 */
178 void deleteEvent(String mediapackageId) throws NotFoundException, SchedulerServiceDatabaseException;
179
180 /**
181 * Get the event with the given mediapackage id for the current organization.
182 *
183 * @param mediapackageId
184 * The mediapackage id to look for
185 *
186 * @return The event or nothing, if the event couldn't be found.
187 *
188 * @throws SchedulerServiceDatabaseException
189 * If the database cannot be queried.
190 */
191 Opt<ExtendedEventDto> getEvent(String mediapackageId) throws SchedulerServiceDatabaseException;
192
193 /**
194 * Get the event with the given mediapackage id and organization.
195 *
196 * @param mediapackageId
197 * The mediapackage id to look for
198 * @param orgId
199 * The organization id to look for
200 *
201 * @return The event or nothing, if the event couldn't be found.
202 *
203 * @throws SchedulerServiceDatabaseException
204 * If the database cannot be queried.
205 */
206 Opt<ExtendedEventDto> getEvent(String mediapackageId, String orgId) throws SchedulerServiceDatabaseException;
207
208 /**
209 * Get all events from the scheduler for the current organizations.
210 *
211 * @return The list of events.
212 *
213 * @throws SchedulerServiceDatabaseException
214 * If the database cannot be queried.
215 */
216 List<ExtendedEventDto> getEvents() throws SchedulerServiceDatabaseException;
217
218 /**
219 * Nulls recording state and recording last heard of of the given media package.
220 * @param mediapackageId
221 * The mediapackage id to look for
222 * @throws NotFoundException
223 * if there is no element with specified ID
224 * @throws SchedulerServiceDatabaseException
225 * If the database cannot be queried.
226 */
227 void resetRecordingState(String mediapackageId) throws NotFoundException, SchedulerServiceDatabaseException;
228
229 /**
230 * Retrieve the number of events.
231 *
232 * @return The number of events.
233 * @throws SchedulerServiceDatabaseException
234 * If the database cannot be queried.
235 */
236 int countEvents() throws SchedulerServiceDatabaseException;
237 }