1 package org.apache.fulcrum.upload;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.util.List;
23
24 import javax.portlet.ActionRequest;
25 import javax.servlet.http.HttpServletRequest;
26
27 import org.apache.avalon.framework.service.ServiceException;
28 import org.apache.commons.fileupload.FileItem;
29 import org.apache.commons.fileupload.FileItemIterator;
30
31 /**
32 * <p>
33 * This service handles parsing <code>multipart/form-data</code> POST requests
34 * and turning them into form fields and uploaded files. This can be either
35 * performed automatically by the <code>org.apache.fulcrum.parser.ParameterParser</code> or manually by a user
36 * defined <code>org.apache.turbine.modules.Action</code>.
37 *
38 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
39 * @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
40 * @version $Id$
41 */
42 public interface UploadService
43
44 {
45 /** Avalon Identifier **/
46 String ROLE = UploadService.class.getName();
47
48 /**
49 * HTTP header.
50 */
51 String CONTENT_TYPE = "Content-type";
52
53 /**
54 * HTTP header.
55 */
56 String CONTENT_DISPOSITION = "Content-disposition";
57
58 /**
59 * HTTP header base type.
60 */
61 String MULTIPART = "multipart";
62
63 /**
64 * HTTP header base type modifier.
65 */
66 String FORM_DATA = "form-data";
67
68 /**
69 * HTTP header base type modifier.
70 */
71 String MIXED = "mixed";
72
73 /**
74 * HTTP header.
75 */
76 String MULTIPART_FORM_DATA = MULTIPART + '/' + FORM_DATA;
77
78 /**
79 * HTTP header.
80 */
81 String MULTIPART_MIXED = MULTIPART + '/' + MIXED;
82
83 /**
84 * The request parameter name for overriding 'repository' property (path).
85 */
86 String REPOSITORY_PARAMETER = "path";
87
88 /**
89 * The key in UploadService properties in TurbineResources.properties
90 * 'repository' property.
91 */
92 String REPOSITORY_KEY = "repository";
93
94 /**
95 * <p>
96 * The default value of 'repository' property (.). This is the directory where
97 * uploaded files will get stored temporarily. Note that "." is whatever the
98 * servlet container chooses to be it's 'current directory'.
99 */
100 String REPOSITORY_DEFAULT = ".";
101
102 /**
103 * w The key in UploadService properties in service configuration 'sizeMax'
104 * property.
105 */
106 String SIZE_MAX_KEY = "sizeMax";
107
108 /**
109 * <p>
110 * The default value of 'sizMax' property (1 megabyte = 1048576 bytes). This is
111 * the maximum size of POST request that will be parsed by the uploader. If you
112 * need to set specific limits for your users, set this property to the largest
113 * limit value, and use an action + no auto upload to enforce limits.
114 *
115 */
116 int SIZE_MAX_DEFAULT = 1048576;
117
118 /**
119 * The key in UploadService properties in TurbineResources.properties
120 * 'sizeThreshold' property.
121 */
122 String SIZE_THRESHOLD_KEY = "sizeThreshold";
123
124 /**
125 * <p>
126 * The default value of 'sizeThreshold' property (10 kilobytes = 10240 bytes).
127 * This is the maximum size of a POST request that will have it's components
128 * stored temporarily in memory, instead of disk.
129 */
130 int SIZE_THRESHOLD_DEFAULT = 10240;
131
132 /**
133 * The key in UploadService properties in TurbineResources.properties
134 * 'headerEncoding' property.
135 */
136 String HEADER_ENCODING_KEY = "headerEncoding";
137
138 /**
139 * <p>
140 * The default value of 'headerEncoding' property (.). The value has been
141 * decided by copying from DiskFileItem class
142 */
143 String HEADER_ENCODING_DEFAULT = "ISO-8859-1";
144
145 /**
146 * <p>
147 * Parses a <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> compliant
148 * <code>multipart/form-data</code> stream.
149 * </p>
150 *
151 * @param req The servlet request to be parsed.
152 * @return list of file items
153 * @throws ServiceException Problems reading/parsing the request or storing
154 * the uploaded file(s).
155 */
156 List<FileItem> parseRequest(HttpServletRequest req) throws ServiceException;
157
158 /**
159 * <p>
160 * Parses a <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> compliant
161 * <code>multipart/form-data</code> stream.
162 * </p>
163 *
164 * @param req The servlet request to be parsed.
165 * @param path The location where the files should be stored.
166 * @return List of FileItem parts
167 * @throws ServiceException Problems reading/parsing the request or storing
168 * the uploaded file(s).
169 */
170 List<FileItem> parseRequest(HttpServletRequest req, String path) throws ServiceException;
171
172 /**
173 * <p>
174 * Parses a <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> compliant
175 * <code>multipart/form-data</code> stream.
176 * </p>
177 *
178 * @param req The servlet request to be parsed.
179 * @param sizeThreshold the max size in bytes to be stored in memory
180 * @param sizeMax the maximum allowed upload size in bytes
181 * @param path The location where the files should be stored.
182 * @return List of FileItem parts
183 * @throws ServiceException Problems reading/parsing the request or storing
184 * the uploaded file(s).
185 */
186 List<FileItem> parseRequest(HttpServletRequest req, int sizeThreshold, int sizeMax, String path)
187 throws ServiceException;
188
189 /**
190 * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
191 * compliant <code>multipart/form-data</code> stream.
192 *
193 * @param req The servlet request to be parsed.
194 *
195 * @return An iterator to instances of <code>FileItemStream</code> parsed from
196 * the request, in the order that they were transmitted.
197 *
198 * @throws ServiceException if there are problems reading/parsing the request or
199 * storing files. This may also be a network error
200 * while communicating with the client or a problem
201 * while storing the uploaded content.
202 */
203 FileItemIterator getItemIterator(HttpServletRequest req) throws ServiceException;
204
205 /**
206 * <p>
207 * Parses a <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> compliant
208 * <code>multipart/form-data</code> stream.
209 * </p>
210 *
211 * @param req The portlet request to be parsed.
212 * @return List of FileItem parts
213 * @throws ServiceException Problems reading/parsing the request or storing
214 * the uploaded file(s).
215 */
216 List<FileItem> parseRequest(ActionRequest req) throws ServiceException;
217
218 /**
219 * <p>
220 * Parses a <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> compliant
221 * <code>multipart/form-data</code> stream.
222 * </p>
223 *
224 * @param req The portlet request to be parsed.
225 * @param path The location where the files should be stored.
226 * @return List of FileItem parts
227 * @throws ServiceException Problems reading/parsing the request or storing
228 * the uploaded file(s).
229 */
230 List<FileItem> parseRequest(ActionRequest req, String path) throws ServiceException;
231
232 /**
233 * <p>
234 * Parses a <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a> compliant
235 * <code>multipart/form-data</code> stream.
236 * </p>
237 *
238 * @param req The portlet request to be parsed.
239 * @param sizeThreshold the max size in bytes to be stored in memory
240 * @param sizeMax the maximum allowed upload size in bytes
241 * @param path The location where the files should be stored.
242 * @return The list of FileItem parts uploaded
243 * @throws ServiceException Problems reading/parsing the request or storing
244 * the uploaded file(s).
245 */
246 List<FileItem> parseRequest(ActionRequest req, int sizeThreshold, int sizeMax, String path) throws ServiceException;
247
248 /**
249 * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
250 * compliant <code>multipart/form-data</code> stream.
251 *
252 * @param req The portlet request to be parsed.
253 *
254 * @return An iterator to instances of <code>FileItemStream</code> parsed from
255 * the request, in the order that they were transmitted.
256 *
257 * @throws ServiceException if there are problems reading/parsing the request or
258 * storing files. This may also be a network error
259 * while communicating with the client or a problem
260 * while storing the uploaded content.
261 */
262 FileItemIterator getItemIterator(ActionRequest req) throws ServiceException;
263
264 /**
265 * <p>
266 * Retrieves the value of <code>size.max</code> property of the
267 * {@link org.apache.fulcrum.upload.UploadService}.
268 *
269 * @return The maximum upload size.
270 */
271 long getSizeMax();
272
273 /**
274 * <p>
275 * Retrieves the value of <code>size.threshold</code> property of
276 * {@link org.apache.fulcrum.upload.UploadService}.
277 *
278 * @return The threshold beyond which files are written directly to disk.
279 */
280 long getSizeThreshold();
281
282 /**
283 * <p>
284 * Retrieves the value of the <code>repository</code> property of
285 * {@link org.apache.fulcrum.upload.UploadService}.
286 *
287 * @return The repository.
288 */
289 String getRepository();
290
291 /**
292 * <p>
293 * Retrieves the value of the <code>headerEncoding</code> property of
294 * {@link org.apache.fulcrum.upload.UploadService}.
295 *
296 * @return Returns the headerEncoding.
297 */
298 String getHeaderEncoding();
299
300 /**
301 * Utility method that determines whether the request contains multipart
302 * content.
303 *
304 * @param req The servlet request to be evaluated. Must be non-null.
305 *
306 * @return <code>true</code> if the request is multipart; <code>false</code>
307 * otherwise.
308 */
309 boolean isMultipart(HttpServletRequest req);
310
311 /**
312 * Utility method that determines whether the request contains multipart
313 * content.
314 *
315 * @param req The portlet request to be evaluated. Must be non-null.
316 *
317 * @return <code>true</code> if the request is multipart; <code>false</code>
318 * otherwise.
319 */
320 boolean isMultipart(ActionRequest req);
321 }