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.workingfilerepository.api;
23
24 import org.opencastproject.storage.StorageUsage;
25 import org.opencastproject.util.NotFoundException;
26
27 import java.io.IOException;
28 import java.io.InputStream;
29 import java.net.URI;
30
31 /**
32 * The Working File Repository is a file storage service that supports the lecture capture system. It may be used by
33 * other clients, but is neither intended nor required to be used by other systems.
34 */
35 public interface WorkingFileRepository extends StorageUsage {
36
37 /** The character encoding used for URLs */
38 String CHAR_ENCODING = "UTF-8";
39
40 /** Path prefix for working file repository uris */
41 String URI_PREFIX = "/files/";
42
43 /** Path prefix for collection items */
44 String COLLECTION_PATH_PREFIX = "/collection/";
45
46 /** Path prefix for mediapackage elements */
47 String MEDIAPACKAGE_PATH_PREFIX = "/mediapackage/";
48
49 /** The job type we use to register with the remote services manager */
50 String SERVICE_TYPE = "org.opencastproject.files";
51
52 /**
53 * Gets the base URI for this service.
54 *
55 * @return The base URI
56 */
57 URI getBaseUri();
58
59 /**
60 * Store the data stream under the given media package and element IDs with filename as name of the file.
61 *
62 * @param mediaPackageID
63 * the media package identifier
64 * @param mediaPackageElementID
65 * the media package element identifier
66 * @param filename
67 * the file name to use
68 * @param in
69 * the input stream
70 * @return The URL to access this file
71 * @throws IOException
72 * if the input stream cannot be accessed or the element cannot be written to the repository
73 * @throws IllegalArgumentException
74 * if a <code>URI</code> cannot be created from the arguments
75 */
76 URI put(String mediaPackageID, String mediaPackageElementID, String filename, InputStream in) throws IOException,
77 IllegalArgumentException;
78
79 /**
80 * Stream the file stored under the given media package and element IDs.
81 *
82 * @param mediaPackageID
83 * the media package identifier
84 * @param mediaPackageElementID
85 * the media package element identifier
86 * @return the media package element contents
87 * @throws IOException
88 * if there is a problem reading the data
89 * @throws NotFoundException
90 * if the media package element can't be found
91 */
92 InputStream get(String mediaPackageID, String mediaPackageElementID) throws IOException, NotFoundException;
93
94 /**
95 * Get the URL for a file stored under the given collection.
96 *
97 * @param collectionID
98 * the collection identifier
99 * @param fileName
100 * the file name
101 * @return the file's uri
102 * @throws IllegalArgumentException
103 * if a <code>URI</code> cannot be created from the arguments
104 */
105 URI getCollectionURI(String collectionID, String fileName) throws IllegalArgumentException;
106
107 /**
108 * Get the URL for a file stored under the given media package and element IDs. This may be called for mediapackages,
109 * elements, or files that have not yet been stored in the repository.
110 *
111 * @param mediaPackageID
112 * the media package identifier
113 * @param mediaPackageElementID
114 * the media package element identifier
115 * @return the URI to this resource
116 * @throws IllegalArgumentException
117 * if a <code>URI</code> cannot be created from the arguments
118 */
119 URI getURI(String mediaPackageID, String mediaPackageElementID) throws IllegalArgumentException;
120
121 /**
122 * Get the URL for a file stored under the given media package and element IDs. This may be called for mediapackages,
123 * elements, or files that have not yet been stored in the repository.
124 *
125 * @param mediaPackageID
126 * the media package identifier
127 * @param mediaPackageElementID
128 * the media package element identifier
129 * @param fileName
130 * the file name
131 * @return the URI to this resource
132 * @throws IllegalArgumentException
133 * if a <code>URI</code> cannot be created from the arguments
134 */
135 URI getURI(String mediaPackageID, String mediaPackageElementID, String fileName) throws IllegalArgumentException;
136
137 String toSafeName(String fileName);
138
139 /**
140 * Delete the file stored at the given media package and element IDs.
141 *
142 * @param mediaPackageID
143 * the media package identifier
144 * @param mediaPackageElementID
145 * the media package element identifier
146 * @throws IOException
147 * if the element cannot be deleted
148 */
149 boolean delete(String mediaPackageID, String mediaPackageElementID) throws IOException;
150
151 /**
152 * Puts a file into a collection, overwriting the existing file if present.
153 *
154 * @param collectionId
155 * The collection identifier
156 * @param fileName
157 * The filename to use in storing the input stream
158 * @param in
159 * the data to store
160 * @return The URI identifying the file
161 * @throws IOException
162 * if the input stream cannot be accessed or the file cannot be written to the repository
163 */
164 URI putInCollection(String collectionId, String fileName, InputStream in) throws IOException;
165
166 /**
167 * Gets the URIs of the members of this collection
168 *
169 * @param collectionId
170 * the collection identifier
171 * @return the URIs for each member of the collection
172 * @throws NotFoundException
173 * if the collectionId does not exist
174 */
175 URI[] getCollectionContents(String collectionId) throws NotFoundException;
176
177 /**
178 * Removes a file from a collection
179 *
180 * @param collectionId
181 * the collection identifier
182 * @param fileName
183 * the filename to remove
184 * @return <code>true</code> if the file existed and was removed
185 */
186 boolean deleteFromCollection(String collectionId, String fileName) throws IOException;
187
188 /**
189 * Removes a file from a collection, and the parent folder if empty
190 *
191 * @param collectionId
192 * the collection identifier
193 * @param fileName
194 * the filename to remove
195 * @param removeCollection
196 * remove the parent collection folder if empty
197 * @return <code>true</code> if the file existed and was removed
198 */
199 boolean deleteFromCollection(String collectionId, String fileName, boolean removeCollection) throws IOException;
200
201 /**
202 * Moves a file from a collection into a mediapackage
203 *
204 * @param fromCollection
205 * The collection holding the file
206 * @param fromFileName
207 * The filename
208 * @param toMediaPackage
209 * The media package ID to move the file into
210 * @param toMediaPackageElement
211 * the media package element ID of the file
212 * @param toFileName
213 * the name of the resulting file
214 * @return the URI pointing to the file's new location
215 */
216 URI moveTo(String fromCollection, String fromFileName, String toMediaPackage, String toMediaPackageElement,
217 String toFileName) throws NotFoundException, IOException;
218
219 /**
220 * A textual representation of available and total storage
221 *
222 * @return Percentage and numeric values of used storage space
223 */
224 String getDiskSpace();
225
226 /**
227 * Cleans up collection files older than the number of days passed.
228 *
229 * @param collectionId
230 * the collection identifier
231 * @param days
232 * files older than that will be deleted
233 */
234 boolean cleanupOldFilesFromCollection(String collectionId, long days) throws IOException;
235
236
237 /**
238 * Cleans up media files older than the number of days passed.
239 *
240 * @param days
241 * files older than that will be deleted
242 */
243 boolean cleanupOldFilesFromMediaPackage(long days) throws IOException;
244 }