1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package org.apache.commons.fileupload;
17
18 import java.io.File;
19 import java.io.IOException;
20 import java.io.InputStream;
21 import java.io.OutputStream;
22 import java.io.Serializable;
23 import java.io.UnsupportedEncodingException;
24
25 /***
26 * <p> This class represents a file or form item that was received within a
27 * <code>multipart/form-data</code> POST request.
28 *
29 * <p> After retrieving an instance of this class from a {@link
30 * org.apache.commons.fileupload.FileUpload FileUpload} instance (see
31 * {@link org.apache.commons.fileupload.FileUpload
32 * #parseRequest(javax.servlet.http.HttpServletRequest)}), you may
33 * either request all contents of the file at once using {@link #get()} or
34 * request an {@link java.io.InputStream InputStream} with
35 * {@link #getInputStream()} and process the file without attempting to load
36 * it into memory, which may come handy with large files.
37 *
38 * <p> While this interface does not extend
39 * <code>javax.activation.DataSource</code> per se (to avoid a seldom used
40 * dependency), several of the defined methods are specifically defined with
41 * the same signatures as methods in that interface. This allows an
42 * implementation of this interface to also implement
43 * <code>javax.activation.DataSource</code> with minimal additional work.
44 *
45 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
46 * @author <a href="mailto:sean@informage.net">Sean Legassick</a>
47 * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
48 * @author <a href="mailto:martinc@apache.org">Martin Cooper</a>
49 *
50 * @version $Id: FileItem.java 349366 2005-11-28 04:44:57Z martinc $
51 */
52 public interface FileItem
53 extends Serializable {
54
55
56
57
58
59 /***
60 * Returns an {@link java.io.InputStream InputStream} that can be
61 * used to retrieve the contents of the file.
62 *
63 * @return An {@link java.io.InputStream InputStream} that can be
64 * used to retrieve the contents of the file.
65 *
66 * @throws IOException if an error occurs.
67 */
68 InputStream getInputStream()
69 throws IOException;
70
71
72 /***
73 * Returns the content type passed by the browser or <code>null</code> if
74 * not defined.
75 *
76 * @return The content type passed by the browser or <code>null</code> if
77 * not defined.
78 */
79 String getContentType();
80
81
82 /***
83 * Returns the original filename in the client's filesystem, as provided by
84 * the browser (or other client software). In most cases, this will be the
85 * base file name, without path information. However, some clients, such as
86 * the Opera browser, do include path information.
87 *
88 * @return The original filename in the client's filesystem.
89 */
90 String getName();
91
92
93
94
95
96 /***
97 * Provides a hint as to whether or not the file contents will be read
98 * from memory.
99 *
100 * @return <code>true</code> if the file contents will be read from memory;
101 * <code>false</code> otherwise.
102 */
103 boolean isInMemory();
104
105
106 /***
107 * Returns the size of the file item.
108 *
109 * @return The size of the file item, in bytes.
110 */
111 long getSize();
112
113
114 /***
115 * Returns the contents of the file item as an array of bytes.
116 *
117 * @return The contents of the file item as an array of bytes.
118 */
119 byte[] get();
120
121
122 /***
123 * Returns the contents of the file item as a String, using the specified
124 * encoding. This method uses {@link #get()} to retrieve the
125 * contents of the item.
126 *
127 * @param encoding The character encoding to use.
128 *
129 * @return The contents of the item, as a string.
130 *
131 * @throws UnsupportedEncodingException if the requested character
132 * encoding is not available.
133 */
134 String getString(String encoding)
135 throws UnsupportedEncodingException;
136
137
138 /***
139 * Returns the contents of the file item as a String, using the default
140 * character encoding. This method uses {@link #get()} to retrieve the
141 * contents of the item.
142 *
143 * @return The contents of the item, as a string.
144 */
145 String getString();
146
147
148 /***
149 * A convenience method to write an uploaded item to disk. The client code
150 * is not concerned with whether or not the item is stored in memory, or on
151 * disk in a temporary location. They just want to write the uploaded item
152 * to a file.
153 * <p>
154 * This method is not guaranteed to succeed if called more than once for
155 * the same item. This allows a particular implementation to use, for
156 * example, file renaming, where possible, rather than copying all of the
157 * underlying data, thus gaining a significant performance benefit.
158 *
159 * @param file The <code>File</code> into which the uploaded item should
160 * be stored.
161 *
162 * @throws Exception if an error occurs.
163 */
164 void write(File file) throws Exception;
165
166
167 /***
168 * Deletes the underlying storage for a file item, including deleting any
169 * associated temporary disk file. Although this storage will be deleted
170 * automatically when the <code>FileItem</code> instance is garbage
171 * collected, this method can be used to ensure that this is done at an
172 * earlier time, thus preserving system resources.
173 */
174 void delete();
175
176
177 /***
178 * Returns the name of the field in the multipart form corresponding to
179 * this file item.
180 *
181 * @return The name of the form field.
182 */
183 String getFieldName();
184
185
186 /***
187 * Sets the field name used to reference this file item.
188 *
189 * @param name The name of the form field.
190 */
191 void setFieldName(String name);
192
193
194 /***
195 * Determines whether or not a <code>FileItem</code> instance represents
196 * a simple form field.
197 *
198 * @return <code>true</code> if the instance represents a simple form
199 * field; <code>false</code> if it represents an uploaded file.
200 */
201 boolean isFormField();
202
203
204 /***
205 * Specifies whether or not a <code>FileItem</code> instance represents
206 * a simple form field.
207 *
208 * @param state <code>true</code> if the instance represents a simple form
209 * field; <code>false</code> if it represents an uploaded file.
210 */
211 void setFormField(boolean state);
212
213
214 /***
215 * Returns an {@link java.io.OutputStream OutputStream} that can
216 * be used for storing the contents of the file.
217 *
218 * @return An {@link java.io.OutputStream OutputStream} that can be used
219 * for storing the contensts of the file.
220 *
221 * @throws IOException if an error occurs.
222 */
223 OutputStream getOutputStream() throws IOException;
224
225 }