001 package org.apache.fulcrum.upload;
002
003
004 /*
005 * Licensed to the Apache Software Foundation (ASF) under one
006 * or more contributor license agreements. See the NOTICE file
007 * distributed with this work for additional information
008 * regarding copyright ownership. The ASF licenses this file
009 * to you under the Apache License, Version 2.0 (the
010 * "License"); you may not use this file except in compliance
011 * with the License. You may obtain a copy of the License at
012 *
013 * http://www.apache.org/licenses/LICENSE-2.0
014 *
015 * Unless required by applicable law or agreed to in writing,
016 * software distributed under the License is distributed on an
017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018 * KIND, either express or implied. See the License for the
019 * specific language governing permissions and limitations
020 * under the License.
021 */
022
023
024 import java.util.List;
025
026 import javax.servlet.http.HttpServletRequest;
027
028 import org.apache.avalon.framework.service.ServiceException;
029 import org.apache.commons.fileupload.FileItem;
030 import org.apache.commons.fileupload.FileItemIterator;
031
032 /**
033 * <p> This service handles parsing <code>multipart/form-data</code>
034 * POST requests and turning them into form fields and uploaded files.
035 * This can be either performed automatically by the {@link
036 * org.apache.fulcrum.parser.ParameterParser} or manually by an user
037 * defined {@link org.apache.turbine.modules.Action}.
038 *
039 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
040 * @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
041 * @version $Id: UploadService.java 1351114 2012-06-17 15:59:20Z tv $
042 */
043 public interface UploadService
044
045 {
046 /** Avalon Identifier **/
047 String ROLE = UploadService.class.getName();
048
049 /**
050 * HTTP header.
051 */
052 String CONTENT_TYPE = "Content-type";
053
054 /**
055 * HTTP header.
056 */
057 String CONTENT_DISPOSITION = "Content-disposition";
058
059 /**
060 * HTTP header base type.
061 */
062 String MULTIPART = "multipart";
063
064 /**
065 * HTTP header base type modifier.
066 */
067 String FORM_DATA = "form-data";
068
069 /**
070 * HTTP header base type modifier.
071 */
072 String MIXED = "mixed";
073
074 /**
075 * HTTP header.
076 */
077 String MULTIPART_FORM_DATA =
078 MULTIPART + '/' + FORM_DATA;
079
080 /**
081 * HTTP header.
082 */
083 String MULTIPART_MIXED = MULTIPART + '/' + MIXED;
084
085 /**
086 * The request parameter name for overriding 'repository' property
087 * (path).
088 */
089 String REPOSITORY_PARAMETER = "path";
090
091 /**
092 * The key in UploadService properties in
093 * TurbineResources.properties 'repository' property.
094 */
095 String REPOSITORY_KEY = "repository";
096
097 /**
098 * <p> The default value of 'repository' property (.). This is
099 * the directory where uploaded files will get stored temporarily.
100 * Note that "." is whatever the servlet container chooses to be
101 * it's 'current directory'.
102 */
103 String REPOSITORY_DEFAULT = ".";
104
105 /**
106 * w The key in UploadService properties in
107 * service configuration 'sizeMax' property.
108 */
109 String SIZE_MAX_KEY = "sizeMax";
110
111 /**
112 * <p> The default value of 'sizMax' property (1 megabyte =
113 * 1048576 bytes). This is the maximum size of POST request that
114 * will be parsed by the uploader. If you need to set specific
115 * limits for your users, set this property to the largest limit
116 * value, and use an action + no auto upload to enforce limits.
117 *
118 */
119 int SIZE_MAX_DEFAULT = 1048576;
120
121 /**
122 * The key in UploadService properties in
123 * TurbineResources.properties 'sizeThreshold' property.
124 */
125 String SIZE_THRESHOLD_KEY = "sizeThreshold";
126
127 /**
128 * <p> The default value of 'sizeThreshold' property (10
129 * kilobytes = 10240 bytes). This is the maximum size of a POST
130 * request that will have it's components stored temporarily in
131 * memory, instead of disk.
132 */
133 int SIZE_THRESHOLD_DEFAULT = 10240;
134
135 /**
136 * The key in UploadService properties in
137 * TurbineResources.properties 'headerEncoding' property.
138 */
139 String HEADER_ENCODING_KEY = "headerEncoding";
140
141 /**
142 * <p> The default value of 'headerEncoding' property (.).
143 * The value has been decided by copying from DiskFileItem class
144 */
145 String HEADER_ENCODING_DEFAULT = "ISO-8859-1";
146
147 /**
148 * <p>Parses a <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
149 * compliant <code>multipart/form-data</code> stream.</p>
150 *
151 * @param req The servlet request to be parsed.
152 * @exception ServiceException Problems reading/parsing the
153 * request or storing the uploaded file(s).
154 */
155 List<FileItem> parseRequest(HttpServletRequest req)
156 throws ServiceException;
157
158 /**
159 * <p>Parses a <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
160 * compliant <code>multipart/form-data</code> stream.</p>
161 *
162 * @param req The servlet request to be parsed.
163 * @param path The location where the files should be stored.
164 * @exception ServiceException Problems reading/parsing the
165 * request or storing the uploaded file(s).
166 */
167 List<FileItem> parseRequest(HttpServletRequest req, String path)
168 throws ServiceException;
169
170 /**
171 * <p>Parses a <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
172 * compliant <code>multipart/form-data</code> stream.</p>
173 *
174 * @param req The servlet request to be parsed.
175 * @param sizeThreshold the max size in bytes to be stored in memory
176 * @param sizeMax the maximum allowed upload size in bytes
177 * @param path The location where the files should be stored.
178 * @exception ServiceException Problems reading/parsing the
179 * request or storing the uploaded file(s).
180 */
181 List<FileItem> parseRequest(HttpServletRequest req, int sizeThreshold,
182 int sizeMax, String path)
183 throws ServiceException;
184
185
186 /**
187 * Processes an <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>
188 * compliant <code>multipart/form-data</code> stream.
189 *
190 * @param req The servlet request to be parsed.
191 *
192 * @return An iterator to instances of <code>FileItemStream</code>
193 * parsed from the request, in the order that they were
194 * transmitted.
195 *
196 * @throws ServiceException if there are problems reading/parsing
197 * the request or storing files. This
198 * may also be a network error while
199 * communicating with the client or a
200 * problem while storing the uploaded
201 * content.
202 */
203 FileItemIterator getItemIterator(HttpServletRequest req) throws ServiceException;
204
205
206 /**
207 * <p> Retrieves the value of <code>size.max</code> property of the
208 * {@link org.apache.fulcrum.upload.UploadService}.
209 *
210 * @return The maximum upload size.
211 */
212 long getSizeMax();
213
214 /**
215 * <p> Retrieves the value of <code>size.threshold</code> property of
216 * {@link org.apache.fulcrum.upload.UploadService}.
217 *
218 * @return The threshold beyond which files are written directly to disk.
219 */
220 long getSizeThreshold();
221
222 /**
223 * <p> Retrieves the value of the <code>repository</code> property of
224 * {@link org.apache.fulcrum.upload.UploadService}.
225 *
226 * @return The repository.
227 */
228 String getRepository();
229
230 /**
231 * <p> Retrieves the value of the <code>headerEncoding</code> property of
232 * {@link org.apache.fulcrum.upload.UploadService}.
233 *
234 * @return Returns the headerEncoding.
235 */
236 String getHeaderEncoding();
237
238 /**
239 * Utility method that determines whether the request contains multipart
240 * content.
241 *
242 * @param req The servlet request to be evaluated. Must be non-null.
243 *
244 * @return <code>true</code> if the request is multipart;
245 * <code>false</code> otherwise.
246 */
247 boolean isMultipart(HttpServletRequest req);
248
249 }