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 package org.opencastproject.publication.api;
22
23 import org.opencastproject.job.api.Job;
24 import org.opencastproject.mediapackage.MediaPackage;
25 import org.opencastproject.mediapackage.MediaPackageElement;
26 import org.opencastproject.mediapackage.MediaPackageElementFlavor;
27 import org.opencastproject.mediapackage.MediaPackageException;
28 import org.opencastproject.mediapackage.Publication;
29 import org.opencastproject.util.NotFoundException;
30
31 import java.util.Set;
32
33 /**
34 * Publishes elements from MediaPackages to OAI-PMH.
35 */
36 public interface OaiPmhPublicationService {
37
38 /**
39 * Identifier for service registration and location
40 */
41 String JOB_TYPE = "org.opencastproject.publication.oaipmh";
42
43 /**
44 * The Opencast publication channel id is created from the OAI-PMH channel name prefixed by the
45 * {@link #PUBLICATION_CHANNEL_PREFIX}.
46 */
47 String PUBLICATION_CHANNEL_PREFIX = "oaipmh-";
48
49 /**
50 * Separator used to separate strings when serializing arrays of strings.
51 */
52 String SEPARATOR = ";;";
53
54 /**
55 * Publishes some media package elements.
56 *
57 * @param mediaPackage
58 * the media package
59 * @param repository
60 * the OAI-PMH repository
61 * @param downloadElementIds
62 * the download element ids to publish
63 * @param streamingElementIds
64 * the streaming element ids to publish
65 * @param checkAvailability
66 * whether to check the distributed download artifacts are available at its URL
67 * @return The job
68 * @throws PublicationException
69 * if there was a problem publishing the media
70 * @throws MediaPackageException
71 * if there was a problem with the mediapackage element
72 */
73 Job publish(
74 MediaPackage mediaPackage,
75 String repository,
76 Set<String> downloadElementIds,
77 Set<String> streamingElementIds,
78 boolean checkAvailability
79 ) throws PublicationException, MediaPackageException;
80
81 /**
82 * Updates the given media package in the Oai-Pmh storage incrementally, i.e. without retracting
83 * the whole media package.
84 *
85 * @param mediaPackage
86 * The media package to publish the element for
87 * @param repository
88 * The OAI-PMH repository
89 * @param downloadElements
90 * the download elements to publish
91 * @param streamingElements
92 * the streaming elements to publish
93 * @param retractDownloadFlavors
94 * flavors to use to search for download elements to retract.
95 * @param retractStreamingFlavors
96 * flavors to use to search for streaming elements to retract.
97 * @param publications
98 * the publications to update
99 * @param checkAvailability
100 * whether to check the distributed download artifacts are available at their URLs
101 *
102 * @return The job which performs the operation (The job payload will hold the publication with
103 * the updated media package).
104 *
105 * @throws PublicationException
106 * if the job could not be created.
107 */
108 Job replace(
109 MediaPackage mediaPackage,
110 String repository,
111 Set<? extends MediaPackageElement> downloadElements,
112 Set<? extends MediaPackageElement> streamingElements,
113 Set<MediaPackageElementFlavor> retractDownloadFlavors,
114 Set<MediaPackageElementFlavor> retractStreamingFlavors,
115 Set<? extends Publication> publications,
116 boolean checkAvailability
117 ) throws PublicationException;
118
119 /**
120 * Synchronously updates the given media package in the Oai-Pmh storage incrementally,
121 * i.e. without retracting the whole media package.
122 *
123 * @param mediaPackage
124 * The media package to publish the element for
125 * @param repository
126 * The OAI-PMH repository
127 * @param downloadElements
128 * the download elements to publish
129 * @param streamingElements
130 * the streaming elements to publish
131 * @param retractDownloadFlavors
132 * flavors to use to search for download elements to retract.
133 * @param retractStreamingFlavors
134 * flavors to use to search for streaming elements to retract.
135 * @param publications
136 * the publications to update
137 * @param checkAvailability
138 * whether to check the distributed download artifacts are available at their URLs
139 *
140 * @return The publication with the updated media package.
141 *
142 * @throws PublicationException
143 * if the job could not be created.
144 * @throws MediaPackageException
145 * if distribution failed.
146 */
147 Publication replaceSync(
148 MediaPackage mediaPackage,
149 String repository,
150 Set<? extends MediaPackageElement> downloadElements,
151 Set<? extends MediaPackageElement> streamingElements,
152 Set<MediaPackageElementFlavor> retractDownloadFlavors,
153 Set<MediaPackageElementFlavor> retractStreamingFlavors,
154 Set<? extends Publication> publications,
155 boolean checkAvailability
156 ) throws PublicationException, MediaPackageException;
157
158 /**
159 * Retract a media package from the publication channel.
160 *
161 * @param mediaPackage
162 * the media package
163 * @param repository
164 * the OAI-PMH repository
165 * @throws NotFoundException
166 * if there was no mediapackage to retract from this channel
167 * @throws PublicationException
168 * if there was a problem retracting the mediapackage
169 */
170 Job retract(MediaPackage mediaPackage, String repository) throws PublicationException, NotFoundException;
171
172 /**
173 * Update all media package elements that match the flavors and tags. Also update the media
174 * package in the given OAI-PMH repository.
175 *
176 * @param mediaPackage media package with updated elements
177 * @param repository OAI-PMH repository where to update the media package
178 * @param flavors updated media package element flavors
179 * @param tags updated media package element tags
180 * @param checkAvailability whether to check the distributed download artifacts are available at its URL
181 * @return The job to update the media package
182 * @throws PublicationException if there was a problem publishing the media
183 * @throws MediaPackageException if there was a problem with the media package element
184 */
185 Job updateMetadata(
186 MediaPackage mediaPackage,
187 String repository,
188 Set<String> flavors,
189 Set<String> tags,
190 boolean checkAvailability
191 ) throws PublicationException, MediaPackageException;
192 }