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