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
23 package org.opencastproject.search.api;
24
25 import org.opencastproject.job.api.Job;
26 import org.opencastproject.mediapackage.MediaPackage;
27 import org.opencastproject.mediapackage.MediaPackageException;
28 import org.opencastproject.security.api.Organization;
29 import org.opencastproject.security.api.UnauthorizedException;
30 import org.opencastproject.serviceregistry.api.ServiceRegistryException;
31 import org.opencastproject.util.NotFoundException;
32
33 import org.apache.commons.lang3.tuple.Pair;
34 import org.elasticsearch.search.builder.SearchSourceBuilder;
35
36 import java.util.Collection;
37
38 /**
39 * Provides search capabilities, possibly to the engage tools, possibly to other services.
40 */
41 public interface SearchService {
42
43 enum IndexEntryType {
44 Episode, Series
45 }
46
47 /**
48 * Identifier for service registration and location
49 */
50 String JOB_TYPE = "org.opencastproject.search";
51
52 /**
53 * Adds the media package to the search index.
54 *
55 * @param mediaPackage
56 * the media package
57 * @throws SearchException
58 * if an error occurs while adding the media package
59 * @throws MediaPackageException
60 * if an error occurs accessing the media package
61 * @throws UnauthorizedException
62 * if the current user is not authorized to add this media package to the search index
63 * @throws ServiceRegistryException
64 * if the job for adding the mediapackage can not be created
65 */
66 Job add(MediaPackage mediaPackage) throws SearchException, MediaPackageException, UnauthorizedException,
67 ServiceRegistryException;
68
69 /**
70 * Returns a list of {@link Organization},{@link MediaPackage} pairs of mediapackages within a series.
71 * Note that the Organization should always be the same since series should not cross organizational bounds.
72 *
73 * @param seriesId
74 * the series ID to query
75 * @return
76 * A list of {@link Organization},{@link MediaPackage} pairs of mediapackages within the series.
77 */
78 Collection<Pair<Organization, MediaPackage>> getSeries(String seriesId);
79
80 /**
81 * Immediately adds the mediapackage to the search index.
82 *
83 * @param mediaPackage
84 * the media package
85 * @throws SearchException
86 * if the media package cannot be added to the search index
87 * @throws IllegalArgumentException
88 * if the mediapackage is <code>null</code>
89 * @throws UnauthorizedException
90 * if the user does not have the rights to add the mediapackage
91 */
92 void addSynchronously(MediaPackage mediaPackage)
93 throws SearchException, IllegalArgumentException, UnauthorizedException;
94
95 /**
96 * Removes the media package identified by <code>mediaPackageId</code> from the search index.
97 *
98 * @param mediaPackageId
99 * id of the media package to remove
100 * @return <code>true</code> if the episode was found and deleted
101 * @throws SearchException
102 * if an error occurs while removing the media package
103 * @throws UnauthorizedException
104 * if the current user is not authorized to remove this mediapackage from the search index
105 */
106 Job delete(String mediaPackageId) throws SearchException, UnauthorizedException, NotFoundException;
107
108 /**
109 * Removes the series identified by <code>seriseId</code> from the search index. Does *not* remove the associated
110 * events from the index!
111 *
112 * @param seriesId
113 * id of the series to remove
114 * @return <code>true</code> if the series was found and deleted
115 * @throws SearchException
116 * if an error occurs while removing the series
117 * @throws UnauthorizedException
118 * if the current user is not authorized to remove this series from the search index
119 */
120 Job deleteSeries(String seriesId) throws SearchException, UnauthorizedException, NotFoundException;
121
122 /**
123 * Immediately removes the given mediapackage from the search service.
124 *
125 * @param mediaPackageId
126 * the mediapackage
127 * @return <code>true</code> if the mediapackage was deleted
128 * @throws SearchException
129 * if deletion failed
130 */
131 boolean deleteSynchronously(String mediaPackageId) throws SearchException;
132
133 /**
134 * Gets the {@link MediaPackage} for an event, based on its mediapackage ID.
135 *
136 * @param mediaPackageId
137 * The ID of the mediapackage in question
138 * @return
139 * The {@link MediaPackage}
140 * @throws NotFoundException
141 * If the mediapackage is not found.
142 * @throws SearchException
143 * If an error occurs while searching for the mediapackage.
144 * @throws UnauthorizedException
145 * if the current user is not authorized to view this mediapackage.
146 */
147 MediaPackage get(String mediaPackageId) throws NotFoundException, SearchException, UnauthorizedException;
148
149 /**
150 * Searches the index based on a {@link SearchSourceBuilder}'s query
151 *
152 * @param searchSource
153 * The {@link SearchSourceBuilder} defining the search query
154 * @return
155 * A {@link SearchResultList} of the search's results
156 * @throws SearchException
157 * If an error occurs while searching the index.
158 */
159 SearchResultList search(SearchSourceBuilder searchSource) throws SearchException;
160 }