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.series.impl;
23
24 import org.opencastproject.metadata.dublincore.DublinCoreCatalog;
25 import org.opencastproject.security.api.AccessControlList;
26 import org.opencastproject.security.api.UnauthorizedException;
27 import org.opencastproject.series.api.Series;
28 import org.opencastproject.series.impl.persistence.SeriesEntity;
29 import org.opencastproject.util.NotFoundException;
30 import org.opencastproject.util.data.Tuple;
31
32 import java.util.Date;
33 import java.util.List;
34 import java.util.Map;
35 import java.util.Optional;
36
37 /**
38 * API that defines persistent storage of series.
39 *
40 */
41 public interface SeriesServiceDatabase {
42
43 /**
44 * Store (or update) series.
45 *
46 * @param dc
47 * {@link DublinCoreCatalog} representing series
48 * @return Dublin Core catalog representing newly created series or null if series Dublin Core was updated
49 * @throws SeriesServiceDatabaseException
50 * if exception occurs
51 * @throws UnauthorizedException
52 * if the current user is not authorized to perform this action
53 */
54 DublinCoreCatalog storeSeries(DublinCoreCatalog dc) throws SeriesServiceDatabaseException, UnauthorizedException;
55
56 /**
57 * Store access control associated with specified series. IllegalArgumentException is thrown if accessControl
58 * parameter is null.
59 *
60 * @param seriesID
61 * ID of series to associate access control with
62 * @param accessControl
63 * {@link AccessControlList} representing access control rules for specified series
64 * @return true if update happened, false if there was no previous entry
65 * @throws NotFoundException
66 * if series with specified ID does not exist
67 * @throws SeriesServiceDatabaseException
68 * if exception occurred
69 */
70 boolean storeSeriesAccessControl(String seriesID, AccessControlList accessControl) throws NotFoundException,
71 SeriesServiceDatabaseException;
72
73 /**
74 * Removes series from persistent storage.
75 *
76 * @param seriesId
77 * ID of the series to be removed
78 * @throws SeriesServiceDatabaseException
79 * if exception occurs
80 * @throws NotFoundException
81 * if series with specified ID is not found
82 */
83 void deleteSeries(String seriesId) throws SeriesServiceDatabaseException, NotFoundException;
84
85 /**
86 * Removes the series property from persistent storage.
87 *
88 * @param seriesId
89 * ID of the series to be removed.
90 * @param propertyName
91 * The unique name of the property to delete.
92 * @throws SeriesServiceDatabaseException
93 * if exception occurs
94 * @throws NotFoundException
95 * if series with specified ID is not found or if there is no property with the property name
96 */
97 void deleteSeriesProperty(String seriesId, String propertyName) throws SeriesServiceDatabaseException,
98 NotFoundException;
99
100 /**
101 * Returns all series in persistent storage.
102 *
103 * @return {@link Tuple} array representing stored series
104 * @throws SeriesServiceDatabaseException
105 * if exception occurs
106 */
107 List<SeriesEntity> getAllSeries() throws SeriesServiceDatabaseException;
108
109 /**
110 * Returns all series (including deleted ones!) that have been modified in the
111 * given date range {@code from} (inclusive) -- {@code to} (exclusive). At
112 * most {@code limit} many series are returned. ACLs/permissions are NOT
113 * checked as this is only intended to be used in an administrative context.
114 */
115 List<Series> getAllForAdministrativeRead(Date from, Optional<Date> to, int limit)
116 throws SeriesServiceDatabaseException, UnauthorizedException;
117
118 /**
119 * Retrieves ACL for series with given ID.
120 *
121 * @param seriesID
122 * series for which ACL will be retrieved
123 * @return {@link AccessControlList} of series or null if series does not have ACL associated with it
124 * @throws NotFoundException
125 * if series with given ID does not exist
126 * @throws SeriesServiceDatabaseException
127 * if exception occurred
128 */
129 AccessControlList getAccessControlList(String seriesID) throws NotFoundException, SeriesServiceDatabaseException;
130
131 /**
132 * Gets a single series by its identifier.
133 *
134 * @param seriesId
135 * the series identifier
136 * @return the dublin core catalog for this series
137 * @throws NotFoundException
138 * if there is no series with this identifier
139 * @throws SeriesServiceDatabaseException
140 * if there is a problem communicating with the underlying data store
141 */
142 DublinCoreCatalog getSeries(String seriesId) throws NotFoundException, SeriesServiceDatabaseException;
143
144 /**
145 * Get the properties for particular series
146 *
147 * @param seriesId
148 * The unique series id to retrieve the properties for.
149 * @return A {@link Map} of the properties names and values.
150 * @throws NotFoundException
151 * Thrown if the series can't be found.
152 * @throws SeriesServiceDatabaseException
153 * If exception occurred
154 */
155 Map<String, String> getSeriesProperties(String seriesId) throws NotFoundException, SeriesServiceDatabaseException;
156
157 /**
158 * Get a series property if it exists
159 *
160 * @param seriesId
161 * The id used to get the series.
162 * @param propertyName
163 * The unique name for the property.
164 * @return The property value
165 * @throws NotFoundException
166 * Thrown if the series or the property doesn't exist.
167 * @throws SeriesServiceDatabaseException
168 * Thrown for all other Exceptions.
169 */
170 String getSeriesProperty(String seriesId, String propertyName) throws NotFoundException,
171 SeriesServiceDatabaseException;
172
173 int countSeries() throws SeriesServiceDatabaseException;
174
175 /**
176 * Updates a series' property.
177 *
178 * @param seriesId
179 * The id of the series to add or update the property for.
180 * @param propertyName
181 * A unique name for the property.
182 * @param propertyValue
183 * The value for the property.
184 * @throws NotFoundException
185 * Thrown if the series cannot be found.
186 * @throws SeriesServiceDatabaseException
187 * Thrown if another exception occurred
188 */
189 void updateSeriesProperty(String seriesId, String propertyName, String propertyValue) throws NotFoundException,
190 SeriesServiceDatabaseException;
191
192 /**
193 * Returns true if the series with the given identifier contains an element with the given type.
194 *
195 * @param seriesId
196 * the series identifier
197 * @param type
198 * the element type
199 * @return true, if the element exits; false otherwise
200 * @throws SeriesServiceDatabaseException
201 * if there was an error while checking if the element exits
202 */
203 boolean existsSeriesElement(String seriesId, String type) throws SeriesServiceDatabaseException;
204
205 /**
206 * Adds or updates a series element in the series service database.
207 *
208 * @param seriesId
209 * the series identifier
210 * @param type
211 * the element type
212 * @param data
213 * the element data
214 * @return true if the element could be added/updated; false if no such series exists
215 * @throws SeriesServiceDatabaseException
216 * if an error occurs while saving the element in the database
217 */
218 boolean storeSeriesElement(String seriesId, String type, byte[] data) throws SeriesServiceDatabaseException;
219
220 /**
221 * Deletes an element of a given type from a series
222 *
223 * @param seriesId
224 * the series identifier
225 * @param type
226 * the element type
227 * @return true if the element could be deleted; false if no such series/element exists
228 * @throws SeriesServiceDatabaseException
229 * if an error occurs while removing the element from the database
230 */
231 boolean deleteSeriesElement(String seriesId, String type) throws SeriesServiceDatabaseException;
232
233 /**
234 * Returns the data of a series element.
235 *
236 * @param seriesId
237 * the series identifier
238 * @param type
239 * the element type
240 * @return the element data or {@code Opt.none()} if no such series/element exists
241 * @throws SeriesServiceDatabaseException
242 * if an error occurs while retrieving the element from the database
243 */
244 Optional<byte[]> getSeriesElement(String seriesId, String type) throws SeriesServiceDatabaseException;
245
246 /**
247 * Returns all elements of a series or an empty map if the series does not contain any elements. The key of the map
248 * marks the element type.
249 *
250 * @param seriesId
251 * the series identifier
252 * @return a map of series elements or {@code Opt.none()} if no such series exists
253 * @throws SeriesServiceDatabaseException
254 * if an error occurs while retrieving the element from the database
255 */
256 Optional<Map<String, byte[]>> getSeriesElements(String seriesId) throws SeriesServiceDatabaseException;
257
258 }