1 | // |
---|
2 | // $Id: FileData.java 95 2007-05-02 03:27:05Z |
---|
3 | // /C=DE/ST=Baden-Wuerttemberg/O=ISDN4Linux/OU=Fritz |
---|
4 | // Elfert/CN=svn-felfert@isdn4linux.de/emailAddress=fritz@fritz-elfert.de $ |
---|
5 | // |
---|
6 | // jupload - A file upload applet. |
---|
7 | // Copyright 2007 The JUpload Team |
---|
8 | // |
---|
9 | // Created: 2006-11-20 |
---|
10 | // Creator: etienne_sf |
---|
11 | // Last modified: $Date: 2010-06-28 08:35:55 -0300 (Seg, 28 Jun 2010) $ |
---|
12 | // |
---|
13 | // This program is free software; you can redistribute it and/or modify it under |
---|
14 | // the terms of the GNU General Public License as published by the Free Software |
---|
15 | // Foundation; either version 2 of the License, or (at your option) any later |
---|
16 | // version. This program is distributed in the hope that it will be useful, but |
---|
17 | // WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
---|
18 | // FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more |
---|
19 | // details. You should have received a copy of the GNU General Public License |
---|
20 | // along with this program; if not, write to the Free Software Foundation, Inc., |
---|
21 | // 675 Mass Ave, Cambridge, MA 02139, USA. |
---|
22 | |
---|
23 | package wjhk.jupload2.filedata; |
---|
24 | |
---|
25 | import java.io.File; |
---|
26 | import java.io.InputStream; |
---|
27 | import java.util.Date; |
---|
28 | |
---|
29 | import wjhk.jupload2.exception.JUploadException; |
---|
30 | import wjhk.jupload2.exception.JUploadIOException; |
---|
31 | import wjhk.jupload2.policies.UploadPolicy; |
---|
32 | import wjhk.jupload2.upload.FileUploadThread; |
---|
33 | import wjhk.jupload2.upload.helper.ByteArrayEncoder; |
---|
34 | |
---|
35 | /** |
---|
36 | * This class contains all data and methods for a file to upload. The current |
---|
37 | * {@link wjhk.jupload2.policies.UploadPolicy} contains the necessary parameters |
---|
38 | * to personalize the way files must be handled. <BR> |
---|
39 | * The JUpload package provides a default implementation of this class in |
---|
40 | * {@link DefaultFileData}. This default implementation contains all necessary |
---|
41 | * methods to allow upload. You can override it to add new file behaviour. For |
---|
42 | * instance, you could add a XMLFileData, that would check that XML is valid |
---|
43 | * before upload. See the <a href="package-summary.html">package summary</a> for |
---|
44 | * more details about that. <BR> |
---|
45 | * This class is the interface that all FileData must implement. The |
---|
46 | * {@link DefaultFileData} class contains the default implementation for this |
---|
47 | * interface. The {@link PictureFileData} contains another implementation of |
---|
48 | * this interface, adapted to manage pictures (rotation, resizing...). <BR> |
---|
49 | * The instance of FileData is created by the |
---|
50 | * {@link UploadPolicy#createFileData(File, File)} method. This method can be |
---|
51 | * overrided in a new upoad policy, to create an instance of another FileData. |
---|
52 | * See {@link PictureFileData} for an example about FileData customization. |
---|
53 | * |
---|
54 | * @author etienne_sf |
---|
55 | */ |
---|
56 | |
---|
57 | public interface FileData { |
---|
58 | |
---|
59 | /** |
---|
60 | * Called during the upload, by the {@link FileUploadThread}. The FileData |
---|
61 | * instance should then call the |
---|
62 | * {@link ByteArrayEncoder#appendTextProperty(String, String, int)} method |
---|
63 | * to add each file property to the current upload. |
---|
64 | * |
---|
65 | * @param bae |
---|
66 | * The byte encoder, where the properties must be added |
---|
67 | * @param index |
---|
68 | * Index of the file concerned by this value. -1 if this is a |
---|
69 | * global parameter. |
---|
70 | * @throws JUploadIOException |
---|
71 | * Encapsulation of the IOException, if any would occurs. |
---|
72 | * @see ByteArrayEncoder#appendTextProperty(String, String, int) |
---|
73 | */ |
---|
74 | public void appendFileProperties(ByteArrayEncoder bae, int index) |
---|
75 | throws JUploadIOException; |
---|
76 | |
---|
77 | /** |
---|
78 | * Prepare the fileData to upload. For instance, picture data can be resized |
---|
79 | * before upload (see {@link PictureFileData}. This method is called before |
---|
80 | * the upload of this file. If no exception is thrown, then the file is |
---|
81 | * correctly prepared. |
---|
82 | * |
---|
83 | * @see FileUploadThread |
---|
84 | * @throws JUploadException |
---|
85 | * Encapsulation of the Exception, if any error would occurs. |
---|
86 | */ |
---|
87 | public void beforeUpload() throws JUploadException; |
---|
88 | |
---|
89 | /** |
---|
90 | * Get size of upload, which may be different from the actual file length. |
---|
91 | * This call is valid only after a call to {@link #beforeUpload()} and |
---|
92 | * before the call to {@link #afterUpload()}. |
---|
93 | * |
---|
94 | * @return The length of upload. In this class, this is the size of the |
---|
95 | * file, as it isn't transformed for upload. This size may change if |
---|
96 | * encoding is necessary (needs a new FileData class), or if picture |
---|
97 | * is to be resized or rotated. |
---|
98 | * @see PictureFileData |
---|
99 | */ |
---|
100 | public long getUploadLength(); |
---|
101 | |
---|
102 | /** |
---|
103 | * This function is called after upload, whether it is successful or not. It |
---|
104 | * allows fileData to free any resource created for the upload. For |
---|
105 | * instance, {@link PictureFileData#afterUpload()} removes the temporary |
---|
106 | * file, if any was created. |
---|
107 | */ |
---|
108 | public void afterUpload(); |
---|
109 | |
---|
110 | /** |
---|
111 | * This function creates an InputStream from this file. The |
---|
112 | * {@link FileUploadThread} class then reads bytes from it and transfers |
---|
113 | * them to the webserver. The caller is responsible for closing this stream.<BR> |
---|
114 | * This method may only be called when {@link #isPreparedForUpload()} |
---|
115 | * returns true. |
---|
116 | * |
---|
117 | * @throws JUploadException |
---|
118 | * Encapsulation of the Exception, if any would occurs. |
---|
119 | * @throws IllegalStateException |
---|
120 | * When the upload is not prepared (before a call to |
---|
121 | * {@link #beforeUpload()} or after a call to |
---|
122 | * {@link #afterUpload()} |
---|
123 | * @return An InputStream, representing this instance. |
---|
124 | */ |
---|
125 | public InputStream getInputStream() throws JUploadException; |
---|
126 | |
---|
127 | /** |
---|
128 | * Get the original filename. This is the name of the file, into the local |
---|
129 | * hardrive |
---|
130 | * |
---|
131 | * @return The original filename |
---|
132 | */ |
---|
133 | public String getFileName(); |
---|
134 | |
---|
135 | /** |
---|
136 | * @return The extension for the original file. |
---|
137 | */ |
---|
138 | public String getFileExtension(); |
---|
139 | |
---|
140 | /** |
---|
141 | * @return The length of the original file. |
---|
142 | */ |
---|
143 | public long getFileLength(); |
---|
144 | |
---|
145 | /** |
---|
146 | * @return The original file date. |
---|
147 | */ |
---|
148 | public Date getLastModified(); |
---|
149 | |
---|
150 | /** |
---|
151 | * Get the directory of the file. |
---|
152 | * |
---|
153 | * @return The directory where this file is stored. |
---|
154 | */ |
---|
155 | public String getDirectory(); |
---|
156 | |
---|
157 | /** |
---|
158 | * Retrieves the MD5 sum of the file.<BR> |
---|
159 | * Since 5.0.0, this method is is in DefaultFileData, and is calculated |
---|
160 | * depending on the sendMD5Sum applet parameter, during the file preparation |
---|
161 | * file. |
---|
162 | * |
---|
163 | * @return The corresponding MD5 sum. |
---|
164 | * @throws JUploadException |
---|
165 | * @see #beforeUpload() |
---|
166 | */ |
---|
167 | public String getMD5() throws JUploadException; |
---|
168 | |
---|
169 | /** |
---|
170 | * This function return the FileData content type. |
---|
171 | * |
---|
172 | * @return The mimeType for the file. |
---|
173 | */ |
---|
174 | public String getMimeType(); |
---|
175 | |
---|
176 | /** |
---|
177 | * Indicate if this file can be read. Take care of the File.canRead() |
---|
178 | * methods, that seems to be wrong from time to time. |
---|
179 | * |
---|
180 | * @return indicates whether the file can be read or not. |
---|
181 | */ |
---|
182 | public boolean canRead(); |
---|
183 | |
---|
184 | /** |
---|
185 | * Standard getter, for the file described by the FileData instance. |
---|
186 | * |
---|
187 | * @return the File instance associated with this row. |
---|
188 | */ |
---|
189 | public File getFile(); |
---|
190 | |
---|
191 | /** |
---|
192 | * Retrieves the path of this file relative to it's root dir |
---|
193 | * |
---|
194 | * @return This instance's relative path or an empty string if it was not |
---|
195 | * created using a root parameter. |
---|
196 | */ |
---|
197 | public String getRelativeDir(); |
---|
198 | |
---|
199 | /** |
---|
200 | * Indicates whether the file can be uploaded or not. This boolean should be |
---|
201 | * set to true in the call to {@link #beforeUpload()}, and the to false in |
---|
202 | * the call to {@link #afterUpload()}. |
---|
203 | * |
---|
204 | * @return True if the file is ready for upload. |
---|
205 | * @throws IllegalStateException |
---|
206 | * When the upload is not prepared (before a call to |
---|
207 | * {@link #beforeUpload()} or after a call to |
---|
208 | * {@link #afterUpload()} |
---|
209 | */ |
---|
210 | public boolean isPreparedForUpload(); |
---|
211 | } |
---|