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.search.impl.persistence;
23
24 import org.opencastproject.mediapackage.MediaPackage;
25 import org.opencastproject.security.api.AccessControlList;
26 import org.opencastproject.security.api.Organization;
27 import org.opencastproject.security.api.UnauthorizedException;
28 import org.opencastproject.util.NotFoundException;
29 import org.opencastproject.util.data.Tuple;
30
31 import org.apache.commons.lang3.tuple.Pair;
32
33 import java.util.Collection;
34 import java.util.Date;
35 import java.util.stream.Stream;
36
37 /**
38 * API that defines persistent storage of series.
39 *
40 */
41 public interface SearchServiceDatabase {
42
43 /**
44 * Returns all search entries in persistent storage.
45 *
46 * @param pagesize
47 * the number of results to get from the database at once
48 * @param offset
49 * the offset into the full result list to fetch
50 * @return {@link Tuple} array of mediapackage-orgid pairs representing stored media packages
51 * @throws SearchServiceDatabaseException
52 * if exception occurs
53 */
54 Stream<Tuple<MediaPackage, String>> getAllMediaPackages(int pagesize, int offset)
55 throws SearchServiceDatabaseException;
56
57 /**
58 * Returns the organization id of the selected media package
59 *
60 * @param mediaPackageId
61 * the media package id to select
62 * @return the organization id
63 * @throws NotFoundException
64 * if media package with specified id and version does not exist
65 * @throws SearchServiceDatabaseException
66 * if an error occurs
67 */
68 String getOrganizationId(String mediaPackageId) throws NotFoundException, SearchServiceDatabaseException;
69
70 /**
71 * Returns the number of mediapackages in persistent storage, including deleted entries.
72 *
73 * @return the number of mediapackages in storage
74 * @throws SearchServiceDatabaseException
75 * if an error occurs
76 */
77 int countMediaPackages() throws SearchServiceDatabaseException;
78
79 /**
80 * Gets a single media package by its identifier.
81 *
82 * @param mediaPackageId
83 * the media package identifier
84 * @return the media package
85 * @throws NotFoundException
86 * if there is no media package with this identifier
87 * @throws SearchServiceDatabaseException
88 * if there is a problem communicating with the underlying data store
89 */
90 MediaPackage getMediaPackage(String mediaPackageId)
91 throws NotFoundException, SearchServiceDatabaseException, UnauthorizedException;
92
93 /**
94 * Gets media packages from a specific series
95 *
96 * @param seriesId the series identifier
97 * @return collection of media packages
98 * @throws SearchServiceDatabaseException if there is a problem communicating with the underlying data store
99 */
100 Collection<Pair<Organization, MediaPackage>> getSeries(String seriesId) throws SearchServiceDatabaseException;
101
102 /**
103 * Retrieves ACL for episode with given ID.
104 *
105 * @param mediaPackageId
106 * media package for which ACL will be retrieved
107 * @return {@link AccessControlList} of media package or null if media package does not have ACL associated with it
108 * @throws NotFoundException
109 * if media package with given ID does not exist
110 * @throws SearchServiceDatabaseException
111 * if exception occurred
112 */
113 AccessControlList getAccessControlList(String mediaPackageId) throws NotFoundException,
114 SearchServiceDatabaseException;
115
116 /**
117 * Retrieves ACLs for series with given ID.
118 *
119 * @param seriesId
120 * series identifier for which ACL will be retrieved
121 * @param excludeIds
122 * list of media package identifier to exclude from the list
123 * @return Collection of pairs of media package id and its {@link AccessControlList} of media packages from the series
124 * @throws SearchServiceDatabaseException
125 * if exception occurred
126 */
127 Collection<Pair<String, AccessControlList>> getAccessControlLists(String seriesId, String ... excludeIds)
128 throws SearchServiceDatabaseException;
129
130 /**
131 * Returns the modification date from the selected media package.
132 *
133 * @param mediaPackageId
134 * the media package id to select
135 * @return the modification date
136 * @throws NotFoundException
137 * if media package with specified id and version does not exist
138 * @throws SearchServiceDatabaseException
139 * if an error occurs
140 */
141 Date getModificationDate(String mediaPackageId) throws NotFoundException, SearchServiceDatabaseException;
142
143 /**
144 * Returns the deletion date from the selected media package.
145 *
146 * @param mediaPackageId
147 * the media package id to select
148 * @return the deletion date
149 * @throws NotFoundException
150 * if media package with specified id does not exist
151 * @throws SearchServiceDatabaseException
152 * if an error occurs
153 */
154 Date getDeletionDate(String mediaPackageId) throws NotFoundException, SearchServiceDatabaseException;
155
156 /**
157 * Removes media package from persistent storage.
158 *
159 * @param mediaPackageId
160 * id of the media package to be removed
161 * @param deletionDate
162 * the deletion date to set
163 * @throws SearchServiceDatabaseException
164 * if exception occurs
165 * @throws NotFoundException
166 * if media package with specified id is not found
167 * @throws UnauthorizedException
168 * if the current user is not authorized to perform this action
169 */
170 void deleteMediaPackage(String mediaPackageId, Date deletionDate) throws SearchServiceDatabaseException,
171 NotFoundException, UnauthorizedException;
172
173 /**
174 * Store (or update) media package.
175 *
176 * @param mediaPackage
177 * {@link MediaPackage} to store
178 * @param acl
179 * the acl of the media package
180 * @param now
181 * the store date
182 * @throws SearchServiceDatabaseException
183 * if exception occurs
184 * @throws UnauthorizedException
185 * if the current user is not authorized to perform this action
186 */
187 void storeMediaPackage(MediaPackage mediaPackage, AccessControlList acl, Date now)
188 throws SearchServiceDatabaseException, UnauthorizedException;
189
190 /**
191 * Checks if a mediapackage is available.
192 *
193 * @param mediaPackageId The ID of the {@link MediaPackage} for which the availability is to be checked
194 * @return True if two conditions are met: The mediapackage exists in the database and the deletion date is not set
195 * @throws SearchServiceDatabaseException if an exception occurs
196 */
197 boolean isAvailable(String mediaPackageId) throws SearchServiceDatabaseException;
198 }