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)
136 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(
158 Optional<String> captureAgentId,
159 Optional<Date> startsFrom,
160 Optional<Date> startsTo,
161 Optional<Date> endFrom,
162 Optional<Date> endTo,
163 Optional<Integer> limit
164 ) throws SchedulerServiceDatabaseException;
165
166 /**
167 * Retrieve all events which have a recording state and a recording last heard.
168 *
169 * @return all events which have a recording state and a recording last heard
170 * @throws SchedulerServiceDatabaseException
171 * If the database cannot be queried.
172 */
173 List<ExtendedEventDto> getKnownRecordings() throws SchedulerServiceDatabaseException;
174
175 /**
176 * Removes the extended event from persistent storage.
177 *
178 * @param mediapackageId
179 * ID of event to be removed
180 * @throws NotFoundException
181 * if there is no element with specified ID
182 * @throws SchedulerServiceDatabaseException
183 * if exception occurred
184 */
185 void deleteEvent(String mediapackageId) throws NotFoundException, SchedulerServiceDatabaseException;
186
187 /**
188 * Get the event with the given mediapackage id for the current organization.
189 *
190 * @param mediapackageId
191 * The mediapackage id to look for
192 *
193 * @return The event or nothing, if the event couldn't be found.
194 *
195 * @throws SchedulerServiceDatabaseException
196 * If the database cannot be queried.
197 */
198 Optional<ExtendedEventDto> getEvent(String mediapackageId) throws SchedulerServiceDatabaseException;
199
200 /**
201 * Get the event with the given mediapackage id and organization.
202 *
203 * @param mediapackageId
204 * The mediapackage id to look for
205 * @param orgId
206 * The organization id to look for
207 *
208 * @return The event or nothing, if the event couldn't be found.
209 *
210 * @throws SchedulerServiceDatabaseException
211 * If the database cannot be queried.
212 */
213 Optional<ExtendedEventDto> getEvent(String mediapackageId, String orgId) throws SchedulerServiceDatabaseException;
214
215 /**
216 * Get all events from the scheduler for the current organizations.
217 *
218 * @return The list of events.
219 *
220 * @throws SchedulerServiceDatabaseException
221 * If the database cannot be queried.
222 */
223 List<ExtendedEventDto> getEvents() throws SchedulerServiceDatabaseException;
224
225 /**
226 * Nulls recording state and recording last heard of of the given media package.
227 * @param mediapackageId
228 * The mediapackage id to look for
229 * @throws NotFoundException
230 * if there is no element with specified ID
231 * @throws SchedulerServiceDatabaseException
232 * If the database cannot be queried.
233 */
234 void resetRecordingState(String mediapackageId) throws NotFoundException, SchedulerServiceDatabaseException;
235
236 /**
237 * Retrieve the number of events.
238 *
239 * @return The number of events.
240 * @throws SchedulerServiceDatabaseException
241 * If the database cannot be queried.
242 */
243 int countEvents() throws SchedulerServiceDatabaseException;
244 }