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