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.workspace.api;
23
24 import org.opencastproject.mediapackage.identifier.Id;
25 import org.opencastproject.storage.StorageUsage;
26 import org.opencastproject.util.NotFoundException;
27
28 import java.io.File;
29 import java.io.IOException;
30 import java.io.InputStream;
31 import java.net.URI;
32
33 /**
34 * Provides efficient access java.io.File objects from potentially remote URIs. This helper service prevents different
35 * service implementations running in the same osgi container from downloading remote files multiple times.
36 *
37 * Additionally, when the system is configured to use shared storage, this performance gain is also achieved across
38 * distributed osgi containers. The methods from WorkingFileRepository are also available as a convenience to clients.
39 */
40 public interface Workspace extends StorageUsage {
41
42 String toSafeName(String fileName);
43
44 /**
45 * Gets a locally cached {@link File} for the given URI.
46 *
47 * @param uri
48 * @return The locally cached file
49 * @throws NotFoundException
50 * if the file does not exist
51 * @throws IOException
52 * if reading the file from the workspace fails
53 */
54 File get(URI uri) throws NotFoundException, IOException;
55
56 /**
57 * Get a locally cached {@link File} for a given URI, optionally ensuring that the file is cached in a unique path
58 * so that it can safely be removed afterwards.
59 *
60 * @param uri
61 * URI to the resource to get
62 * @param uniqueFilename
63 * If a unique path should be used
64 * @return The locally cached file
65 * @throws NotFoundException
66 * if the file does not exist
67 * @throws IOException
68 * if reading the file from the workspace fails
69 */
70 File get(URI uri, boolean uniqueFilename) throws NotFoundException, IOException;
71
72 /**
73 * Get the {@link File} for the given URI directly from the working file repository.
74 * If shared storage is not available, then fall back to get(uri).
75 *
76 * @param uri
77 * URI identifying the resource to load
78 * @return The file
79 * @throws NotFoundException
80 * if the file does not exist
81 * @throws IOException
82 * if reading the file from the working file repository fails
83 */
84 InputStream read(URI uri) throws NotFoundException, IOException;
85
86
87 /**
88 * Gets the base URI for files stored using this service.
89 *
90 * @return The base URI
91 */
92 URI getBaseUri();
93
94 /**
95 * Store the data stream under the given media package and element IDs, specifying a filename.
96 *
97 * @param mediaPackageID
98 * @param mediaPackageElementID
99 * @param fileName
100 * @param in
101 * @throws IOException
102 * if writing the data to the workspace fails
103 * @throws IllegalArgumentException
104 * if a URI cannot be created using the arguments provided
105 */
106 URI put(String mediaPackageID, String mediaPackageElementID, String fileName, InputStream in) throws IOException,
107 IllegalArgumentException;
108
109 /**
110 * Stores the data stream in the given collection, overwriting any data with the same collection id and file name.
111 *
112 * @param collectionId
113 * The collection to use for storing this data
114 * @param fileName
115 * the filename to use in the collection.
116 * @param in
117 * the inputstream
118 * @return the URI of the stored data
119 * @throws IOException
120 * if writing the data to the workspace fails
121 * @throws IllegalArgumentException
122 * if a URI cannot be created using the arguments provided
123 */
124 URI putInCollection(String collectionId, String fileName, InputStream in) throws IOException,
125 IllegalArgumentException;
126
127 /**
128 * Gets the URIs of the members of this collection
129 *
130 * @param collectionId
131 * the collection identifier
132 * @return the URIs for each member of the collection
133 * @throws NotFoundException
134 * if the collection cannot be found
135 * @throws IllegalArgumentException
136 * if a URI cannot be created using the arguments provided
137 */
138 URI[] getCollectionContents(String collectionId) throws NotFoundException, IllegalArgumentException;
139
140 /**
141 * Delete the file stored at the given uri.
142 *
143 * @param uri
144 * the uri
145 * @throws NotFoundException
146 * if there was not file stored under this combination of mediapackage and element IDs.
147 * @throws IOException
148 * if deleting the data from the workspace fails
149 */
150 void delete(URI uri) throws NotFoundException, IOException;
151
152 /**
153 * Delete the file stored at the given media package and element IDs.
154 *
155 * @param mediaPackageID
156 * @param mediaPackageElementID
157 * @throws NotFoundException
158 * if there was not file stored under this combination of mediapackage and element IDs.
159 * @throws IOException
160 * if deleting the data from the workspace fails
161 */
162 void delete(String mediaPackageID, String mediaPackageElementID) throws NotFoundException, IOException;
163
164 /**
165 * Removes a file from a collection
166 *
167 * @param collectionId
168 * the collection identifier
169 * @param fileName
170 * the filename to remove
171 * @throws NotFoundException
172 * if there was no file with the provided name stored under this collection.
173 * @throws IOException
174 * if deleting the data from the workspace fails
175 */
176 void deleteFromCollection(String collectionId, String fileName) throws NotFoundException, IOException;
177
178 /**
179 * Get the URL for a file stored under the given media package and element IDs. MediaPackages may reference elements
180 * that are not yet stored in the working file repository, so this method will return a URI even if the file is not
181 * yet stored.
182 *
183 * @param mediaPackageID
184 * the mediapackage identifier
185 * @param mediaPackageElementID
186 * the element identifier
187 * @return the URI to the file
188 * @throws IllegalArgumentException
189 * if a URI cannot be created using the arguments provided
190 */
191 URI getURI(String mediaPackageID, String mediaPackageElementID) throws IllegalArgumentException;
192
193 /**
194 * Get the URL for a file stored under the given collection.
195 *
196 * @param collectionID
197 * the collection id
198 * @param fileName
199 * the file name
200 * @return the file's uri
201 * @throws IllegalArgumentException
202 * if a URI cannot be created using the arguments provided
203 */
204 URI getCollectionURI(String collectionID, String fileName) throws IllegalArgumentException;
205
206 /**
207 * Moves a file from a collection into a mediapackage
208 *
209 * @param collectionURI
210 * the uri pointing to a workspace collection
211 * @param toMediaPackage
212 * The media package ID to move the file into
213 * @param toMediaPackageElement
214 * the media package element ID of the file
215 * @param toFileName
216 * the name of the resulting file
217 * @return the URI pointing to the file's new location
218 * @throws NotFoundException
219 * if the element identified by <code>collectionURI</code> cannot be found
220 * @throws IOException
221 * if either the original element cannot be read or it cannot be moved to the new location
222 * @throws IllegalArgumentException
223 * if a URI cannot be created using the arguments provided
224 */
225 URI moveTo(URI collectionURI, String toMediaPackage, String toMediaPackageElement, String toFileName)
226 throws NotFoundException, IOException, IllegalArgumentException;
227
228 /**
229 * Cleans up files not belonging to a mediapackage or a collection. If the optional maxAge parameter is set, only
230 * files older than the maxAge are deleted.
231 *
232 * @param maxAge
233 * the maximal age in seconds of a file before deletion is performed
234 */
235 void cleanup(int maxAge);
236
237 /**
238 * Clean up all elements of one media package from the local workspace, not touching the working file repository.
239 *
240 * @param mediaPackageId
241 * Id specifying the media package to remove files for.
242 */
243 void cleanup(Id mediaPackageId) throws IOException;
244
245 /**
246 * Clean up elements of one media package from the local workspace, not touching the working file repository.
247 *
248 * @param mediaPackageId
249 * Id specifying the media package to remove files for.
250 * @param filesOnly
251 * Boolean specifying whether only files or also directories (including the root directory) are deleted.
252 */
253 void cleanup(Id mediaPackageId, boolean filesOnly) throws IOException;
254
255 /**
256 * Returns the workspace's root directory
257 *
258 * @return Path to the workspace root directory
259 */
260 String rootDirectory();
261
262 }