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.fileupload.api;
23
24 import org.opencastproject.fileupload.api.exception.FileUploadException;
25 import org.opencastproject.fileupload.api.job.FileUploadJob;
26 import org.opencastproject.mediapackage.MediaPackage;
27 import org.opencastproject.mediapackage.MediaPackageElementFlavor;
28
29 import java.io.IOException;
30 import java.io.InputStream;
31
32 /**
33 * Interface for a Service that manages upload jobs and receives and handles file parts.
34 *
35 */
36 public interface FileUploadService {
37
38 /**
39 * Returns true is a job with the given ID exists.
40 *
41 * @param id
42 * ID of the job in question
43 * @return true if job exists, false otherwise
44 */
45 boolean hasJob(String id);
46
47 /**
48 * Creates a new upload job with the given metadata.
49 *
50 * @param filename
51 * name of the file to be uploaded
52 * @param fileSize
53 * size of the file
54 * @param chunkSize
55 * size of the file parts that will be uploaded
56 * @param mp
57 * the mediapackage this file should belong to
58 * @return FileUploadJob the job object
59 * @throws FileUploadException
60 */
61 FileUploadJob createJob(String filename, long fileSize, int chunkSize, MediaPackage mp,
62 MediaPackageElementFlavor flavor) throws FileUploadException;
63
64 /**
65 * Returns the upload job with the given ID, throws <code>FileUploadException</code> if the job can not be found.
66 *
67 * @param id
68 * ID of the upload job to retrieve
69 * @return FileUploadJob the job object in question
70 * @throws FileUploadException
71 */
72 FileUploadJob getJob(String id) throws FileUploadException;
73
74 /**
75 * Cleans outdated jobs on the file system
76 */
77 void cleanOutdatedJobs() throws IOException;
78
79 /**
80 * Deletes the job permanently, thus deleting persistent data.
81 *
82 * @param id
83 * ID of the upload job to delete
84 * @throws FileUploadException
85 */
86 void deleteJob(String id) throws FileUploadException;
87
88 /**
89 * Appends the next part to the payload and updates the upload job accordingly.
90 *
91 * @param job
92 * the job object for the upload
93 * @param chunk
94 * the number of the chunk being transfered
95 * @param content
96 * the actual payload data
97 * @throws FileUploadException
98 */
99 void acceptChunk(FileUploadJob job, long chunk, InputStream content) throws FileUploadException;
100
101 /**
102 * Returns an <code>InputStream</code> containing the data from the payload.
103 *
104 * @param job
105 * job to retrieve payload data from
106 * @return InputStream the payload data
107 * @throws FileUploadException
108 */
109 InputStream getPayload(FileUploadJob job) throws FileUploadException;
110
111 }